PAYATHON 2026

如何通过 Git 分支发布软件构建产物或 Releases？

技术老齐

建议先把两个发布文件打成下载包，放到 Bitbucket Downloads 或公司允许使用的文件存储中，再用 Git 标签记录对应的源码版本。用户下载后就能使用，无须克隆仓库。

也可以用 stable 分支单独保存构建产物。对于文件约 5 MB、发布次数不多的小项目，这个方案可以接受。采用这种方式时，建议让产物分支拥有独立于源码的历史，每次发布直接更新文件，不与源码分支合并。

为什么更推荐直接提供下载包？

Git 分支可以记录文件版本，但用户通常只是要获取可执行文件。提供带版本号的 ZIP 下载包，比让用户选择分支、克隆仓库更方便。

工作目录中的文件和仓库历史是两回事。从源码分支创建 stable 后再删除源码，只会让当前目录剩下两个文件，源码仍保留在祖先提交中，普通克隆也会获取这些历史。因此，删除源码文件并不能让这个分支拥有独立的产物历史。

约 5 MB 的二进制文件可以放进 Git，但旧版本会留在历史中，后续发布也会增加仓库体积。实际增长取决于文件变化和 Git 的压缩效果，不能只看当前文件大小。

首选方案：源码打标签，产物单独上传

  1. 提交并验证准备发布的源码。
  2. 为该提交创建版本标签。
  3. 从标签对应的源码构建，打包用户需要的两个文件。
  4. 上传下载包，并提供版本号、运行要求和下载链接。

假设源码主分支名为 main，所有修改都已提交，工作目录干净：

git switch main
git tag -a v1.0.0 -m "Release 1.0.0"
git push origin v1.0.0

构建时要使用 v1.0.0 对应的源码，避免混入未提交的修改。下载包可以命名为：

myapp-1.0.0-windows-x64.zip

文件名中的平台和架构应按实际构建填写。发布记录中还可以保存源码提交哈希、构建环境和 SHA-256 校验值，方便排查用户拿到的是哪个版本。

Git 的附注标签（annotated tag）适合标记发布版本，可以保存标签说明、创建者和日期。如果需要签名，且已配置好签名环境，可以使用 git tag -s。Git 标签文档

Bitbucket Downloads 不可见怎么办？

Bitbucket Cloud 支持 Downloads，也提供上传构建产物的 REST API，既可以手动发布，也可以接入流水线。Bitbucket Downloads 官方说明

公司使用的可能是 Bitbucket Cloud，也可能是自行部署的实例，界面操作不能一概而论。看不到入口时，先确认部署类型、当前账号权限，以及实例提供的功能。

如果 Downloads 不适用，可以使用公司的文件服务器、对象存储或制品仓库。对这个规模的项目，只要下载地址稳定、能够保留旧版本，且目标用户可以正常访问，就足以完成首次发布。

如果采用 stable 分支，如何创建？

建议创建孤立分支（orphan branch）。它的第一个产物提交没有源码提交作为父提交，因此拥有独立历史。

以下命令假设远程仓库中还没有 stable，并在新的本地目录中操作。执行前，将仓库地址、文件名和路径替换为实际值。Git 环境需要支持 git switch：

git clone --no-checkout \
  https://bitbucket.org/WORKSPACE/REPOSITORY.git \
  myapp-release

cd myapp-release
git switch --orphan stable

cp /absolute/path/to/release/myapp.exe .
cp /absolute/path/to/release/runtime.dat .

git add -- myapp.exe runtime.dat
git commit -m "Release binaries for v1.0.0"
git tag -a binary-v1.0.0 -m "Built from source tag v1.0.0"

git push -u origin stable
git push origin binary-v1.0.0

使用新的本地克隆，可以把发布目录与日常开发目录分开。--no-checkout 只是不检出文件，仍然会下载仓库历史；随后创建的孤立分支不会继承源码提交。git switch --orphan 会移除当前已跟踪的文件，因此不要直接在有未保存工作的开发目录中执行这组操作。Git switch 文档

此时，stable 的当前提交中只有两个发布文件，源码仍保留在远程仓库的其他分支中。

后续发布如何维护？是否需要合并？

每次发布时，先在源码仓库中完成修改、验证和版本标记，再把新产物复制到发布目录。

例如，从源码标签 v1.0.1 构建好新文件后，在 myapp-release 目录执行：

git switch stable
git pull --ff-only

cp /absolute/path/to/release-v1.0.1/myapp.exe .
cp /absolute/path/to/release-v1.0.1/runtime.dat .

git add -- myapp.exe runtime.dat
git commit -m "Release binaries for v1.0.1"
git tag -a binary-v1.0.1 -m "Built from source tag v1.0.1"

git push origin stable
git push origin binary-v1.0.1

如果某个文件不再随版本发布，应执行 git rm 删除它，避免旧文件残留。

源码分支和产物分支之间不需要做本地合并，发布时只需构建并复制产物。合并无法生成可执行文件，还可能把源码、删除操作或其他不需要的内容带入目标分支，也无须使用 --allow-unrelated-histories 强行连接两段历史。

是否需要新的 .gitignore？

只要发布目录保持干净，并在执行 git add 时明确指定文件名，就可以不添加 .gitignore。

如果想防止误提交临时文件，可以在 stable 分支根目录放一份 .gitignore，只允许提交它自身和两个发布文件：

/*
!/.gitignore
!/myapp.exe
!/runtime.dat

这份规则适用于两个发布文件都位于根目录的情况。文件名或目录结构变化时，需要同步调整规则。

.gitignore 只影响未跟踪文件，无法隐藏或移除已经提交的源码，也不会清除历史。各分支可以使用不同的 .gitignore，按各自目录的用途维护即可。Git ignore 文档

标签和用户下载有哪些注意事项？

建议区分两类标签：

标签示例指向的内容
v1.0.0用于构建该版本的源码提交
binary-v1.0.0保存该版本发布文件的产物提交

Git 标签名在整个仓库中共享，不属于某个分支，因此这两个提交需要使用不同的标签名。产物提交说明或标签说明中应记录对应的源码标签，最好同时记录完整提交哈希。

stable 可以随着新版本发布继续更新，已发布的版本标签则应保持不变。发布后发现问题，就创建新版本，避免移动旧标签或悄悄替换同名下载包。

如果用户愿意通过 Git 获取最新稳定版本，可以使用浅克隆，只获取 stable 的近期快照：

git clone --depth 1 --single-branch --no-tags \
  --branch stable \
  https://bitbucket.org/WORKSPACE/REPOSITORY.git \
  myapp

其中，--single-branch 限定分支，--depth 1 截断历史，--no-tags 避免自动获取标签。单独使用 --branch stable 主要是选择检出的分支，不足以限制普通克隆获取的其他历史。Git clone 文档

对于只想运行软件的用户，带版本号的下载包仍然更方便。无论使用 Downloads、外部存储还是产物分支，都要确认目标用户具有相应的访问权限。

备注：内容仅供参考。