1. 发行版交付这件事,Git 到底交的是什么
先把话说在前面:Git 里没有名为“发行版交付”的子命令。你哪怕把git help -a翻到底,也找不到一个叫release或者deliver的东西。所谓“发行版交付”,是围绕一个已经冻结的提交,把源码树可靠地封装、标记、导出、校验、送达下游的一整套动作。它的核心矛盾只有一个:上游仓库里存的是“历史 + 对象”,下游需要的却是“某一瞬间的、干净的、可验证的一份源码”。这两者之间隔着一层转换,转换做得好不好,直接决定交付出去的东西会不会被人骂。
这套东西解决的痛点非常具体。你写了个库或者工具,对方要拿去编译、审计、集成到你碰不到的环境里。你直接把仓库地址甩过去,对方 clone 下来,看起来最省事,但问题马上就来:他拿到的是不是你要他拿的那个版本?他 clone 的那一刻分支有没有动?仓库里那些测试夹具、构建产物、编辑器配置、几年前的废弃脚本,他是不是也一起收了?出了问题你让他报 commit hash,他报回来的是他本地改过的那个脏工作区。交付这件事的本质,是把“不确定”消灭掉。
适合看这篇的人分三类。第一类是刚开始独立维护开源库、每次发版都靠手工压缩包的人,你会在这里找到一套能直接照抄的流程;第二类是团队里被安排去搭发布流水线的人,你需要的是方案选型和踩坑清单;第三类是负责接收交付物的一方,比如做集成、做安全审计、做离线部署的同学,你得知道怎么验证手里这个包是不是原封不动的官方产物。三类人的关注点不一样,但都绕不开同一个内核:以提交为锚点,导出可复现的产物。
我自己最早做这件事的时候特别土,直接在本地把项目目录整个复制一份,改个文件夹名,压缩,发出去。结果第一次就翻车了:包里有node_modules,有.env,还有一份半夜调试留下的临时脚本。对方编译报错,我还以为是环境问题,折腾了一下午才发现是我自己包里带了脏东西。从那以后我就明白了,手工打包这件事,只要靠人眼去检查文件列表,就一定会漏。必须让工具替你做过滤,而且过滤规则要写在仓库里、纳入版本控制、参与代码评审。
1.1 三个交付载体与它们的边界
发行版交付的产物形态,大体就三种,选错了会很难受。
第一种是源码归档包,典型产物是xxx-1.2.0.tar.gz或者.zip。它的特点是“一次性、单向、不可追溯” —— 拿到包的人不需要 Git,也不需要网络,解压就能看、就能编译。这是最通用的交付形态,几乎所有的包管理器、系统集成商、下游发行版都认这个。它的代价是丢掉了历史:对方没法git log,没法git bisect,也没法git diff对比两个版本之间到底改了什么。
第二种是仓库打包(bundle),产物是一个.bundle文件,本质上是把 Git 对象库和引用打包成一个单文件。它的特点是“离线但完整”,对方拿到这个文件,git clone一下就能得到一个功能完整的仓库,包含完整历史、标签、分支。适合内网环境、无外网访问的构建机、或者你要把整个项目历史移交给另一个团队。
第三种是直接引用一个远程仓库的特定标签,交付的其实是“一个坐标”而不是“一份数据”。对方执行的是浅克隆或者带过滤的克隆,只拉他需要的那一层。这种方式最省带宽、最贴近“单一事实来源”,但前提是对方能访问你的仓库,且你愿意长期保留这个标签。
三者的选择标准其实很简单:对方能不能访问你的仓库?能,就优先给坐标;不能,再看他要不要历史,要历史给 bundle,不要历史给归档包。我见过有团队为了“稳妥”,每次发版都同时给三种,结果下游不知道该信哪个,反而制造了混乱。选一种,把校验手段给足,比给三种更专业。
1.2 为什么不用“直接 clone”当交付方式
“你 clone 一下 master 就行了”——这句话是交付事故的高发源头。
第一,master/main是一个移动的引用。你说这话的时刻和你对方执行的时刻,中间可能已经合了三个 PR。更麻烦的是,对方如果一周后才来拉,他拿到的和你当时验证过的完全是两份代码,但他会认为他拿到的是“你交付的那个版本”。这种认知错位排查起来极其痛苦,因为双方都不觉得自己有错。
第二,clone会把整个历史带下去。对于一个跑了五年的仓库,.git目录可能比工作区大十倍。做 Docker 镜像构建的时候这一层如果不清理,镜像会白白胖胖多出几百兆。更要命的是历史里可能躺着早就删掉的密钥、测试账号、内部地址,这些东西在git log -p里依然清清楚楚。
第三,clone出来的是一个工作区,工作区会被本地配置污染。core.autocrlf在 Windows 上默认是true,Linux 上是false,同一份代码在两台机器上git status的结果可能不同;.gitignore里的规则在不同 Git 版本下行为也可能有细微差异。交付物应该是确定的字节流,而不是“在某人机器上跑出来的一个目录”。
所以真正的交付动作必须是:先钉死一个不可变的提交,再从这个提交直接导出内容,绕开工作区。这就是git archive存在的意义 —— 它读的是对象库里的 blob,不经过工作区,也不受core.autocrlf影响。这一点很多人不知道,以为 archive 是“把当前目录压缩一下”,其实完全不是。
1.3 一次合格交付的四个硬指标
我判断一次交付做得好不好,就看四条,缺一条我都认为这事儿没做完。
可定位:任何人拿到这个包,都能反查出它对应哪个提交。做法是在包里塞一个版本文件,或者在打包时用export-subst把提交哈希写进某个文件,或者在交付清单里明确写出 commit hash。我倾向于三者都做,因为成本几乎为零。
可校验:包在传输过程中有没有损坏、有没有被替换,对方得能自己验证。这就要求你同时提供一个校验和文件(sha256sum),最好再加上标签签名,让对方能验证“这个包确实出自这个仓库的维护者”。
可复现:同样的提交,今天打一次包,明天再打一次,内容应该一致(至少源码部分一致)。这一点最容易被忽视,后面会专门讲 gzip 时间戳的问题。
无冗余:包里不该有 CI 配置、测试夹具、编辑器配置、构建缓存。判断标准不是“我觉得没用”,而是“对方编译/使用这个包时会不会用到”。想清楚这一点,.gitattributes的export-ignore规则才好写。
2. 使用要求:动手打包之前必须先钉死的几件事
很多人一上来就敲命令,打完发现包名不规范、内容不对、版本号对不上,然后重来一遍。这些返工全是可以避免的,只要你在动手前把下面几件事定下来。
2.1 标签命名与版本号规则
标签是交付的锚点。没有标签就没有交付,这句话我建议你贴在显示器上。分支可以动,提交可以被 rebase 掉,只有打了标签的提交,在正常情况下是稳定的。
命名规则上,我推荐极简的v前缀加语义化版本:v1.2.0、v1.2.1、v2.0.0-rc1。v前缀不是必须的,但它有一个实际好处:git describe默认只认v*开头的标签,不加前缀你得额外传--match参数,多一层心智负担。
版本号本身建议严格遵守三段式语义化约定:主版本号变动代表不兼容的接口变更,次版本号代表向下兼容的功能新增,修订号代表向下兼容的问题修复。预发布版本再加后缀,比如-rc1、-beta2。
有两个细节特别容易出事,我分开说。
第一,不要用轻量标签做发行标记。轻量标签本质上只是个 ref,没有标签对象,不带打标签的人、时间、说明信息,也没法签名。发行版标签一定要用附注标签:
git tag -a v1.2.0 -m "Release 1.2.0: 修复批量导入超时问题,新增 CSV 导出"加了-a之后,git show v1.2.0能看到完整信息,git describe的行为也更符合预期。如果团队有安全要求,再补一个-s走签名标签,后面 2.3 会讲。
第二,标签一旦推出去就不要移动。本地发现打错了,删掉重打没问题;但如果已经推送、已经有人基于它打了包,再强推覆盖,对下游就是灾难 —— 他手里的包和仓库里的标签指向不同提交,而这个差异他永远发现不了。正确做法是发一个新的修订版本号,在变更日志里说明上一个版本作废。这个规矩听起来很硬,但它是发行版的信誉基础。
版本号还有一个隐含要求:它能从提交本身推导出来。也就是说,随便给一个提交,你的脚本应该能算出“它属于哪个版本、距离那个版本多少个提交”。这件事靠git describe完成,具体用法在 3.3 展开。
2.2 用 .gitattributes 控制“什么该进包”
这是整个流程里最被低估的一环。git archive的过滤规则完全来自.gitattributes里的export-ignore属性,而不是.gitignore。这个区别必须掰清楚:
.gitignore管的是“哪些文件不进版本库”,是给git add看的。export-ignore管的是“哪些已入库的文件不进归档包”,是给git archive看的。
一个文件可以既在版本库里,又被排除在归档包外。这正是我们需要的:CI 配置文件应该入库(要评审、要版本化),但不该出现在交付包里(下游不需要,而且里面可能有构建脚本的路径信息)。
我常用的.gitattributes片段大概长这样:
# 交付包排除项 /.github/ export-ignore /.gitlab-ci.yml export-ignore /.editorconfig export-ignore /tests/ export-ignore /docs/screenshots/ export-ignore /scripts/dev/ export-ignore CHANGELOG.md export-ignore CONTRIBUTING.md export-ignore路径以/开头表示从仓库根目录算起,目录末尾的/表示整棵子树都排除。写完之后可以用一条命令验证效果,不要靠猜:
git archive --format=tar v1.2.0 | tar -t | head -50tar -t列出归档内的文件清单,看一眼就知道过滤规则对不对。这一步花十秒钟,能省掉后面半小时的返工。
注意:
.gitattributes本身默认会进包。如果你不想让下游看到你的排除规则(其实一般无所谓),可以给它自己也加一行export-ignore。
还有一个配套属性叫export-subst,作用是在导出时把文件里的$Format:...$占位符替换成真实值。这个后面 3.3 讲版本注入时会细说,这里先记住它和export-ignore是同一套机制的两个方向。
另外要提醒的是,.gitattributes的生效优先级有个坑。默认情况下git archive读的是被归档的那个提交里的.gitattributes,而不是你工作区里的。这个设计其实是对的(保证结果和提交绑定),但你调试规则的时候会觉得“我明明改了怎么没生效”。调试期间加--worktree-attributes参数,让它读工作区的版本,确认无误后再提交。
2.3 签名、权限与可追溯性
如果交付物要跨越组织边界,签名这一步值得花时间。签名标签的做法:
git tag -s v1.2.0 -m "Release 1.2.0" git verify-tag v1.2.0-s会用你的私钥对标签对象签名,下游拿到仓库后git verify-tag就能确认“这个标签确实由持有该私钥的人打的,且标签内容没被篡改”。注意签名保护的是标签对象,不是归档包的字节流。也就是说,签名能证明“这个提交被官方标记为 v1.2.0”,但没法直接证明“你手里这个 tar.gz 就是从那个提交打出来的”。
要把签名和包体绑起来,就得靠校验和:你把sha256sum的结果发在发布公告里,或者把校验和文件也签名。这是一条链:签名标签 → 确定的提交 → 确定的归档内容 → 校验和。链条上每一环都能独立验证,整条链就成立了。
权限方面有个容易忽略的点:归档格式会影响文件权限位的保留。tar格式会保留 Unix 权限位,可执行脚本解压后依然是可执行的;zip格式在这方面的支持要弱一些,某些解压工具会丢掉执行位,导致./configure跑不起来。所以只要你的包里包含需要执行的脚本,优先给tar.gz,zip作为 Windows 用户的补充格式。
同样地,符号链接在 tar 里存的是链接本身,解压后还是链接;在某些 zip 实现里可能被展开成实际文件内容。如果你的仓库里有docs/current -> v1.2这种软链,得提前想好期望行为。
可追溯性还有一个低成本手段:git notes。它可以在不改变提交哈希的前提下,给某个提交挂一段附注。比如在发版后执行:
git notes add -m "构建环境: Linux x86_64, Go 1.21.5, 产物 sha256: 9f2c..." v1.2.0然后在发布页面上把 notes 一起展示出来。这个功能很适合记录“这次发行是在什么环境下构建的”,对事后排查构建相关的问题特别有用。缺点是 notes 默认不随push一起走,需要显式指定 refspec,团队里用之前要先约定好。
3. 执行过程与实现:从冻结提交到可校验产物
这一节是整套流程的主干。我按实际操作顺序走一遍,每一步都说明为什么这么做。
3.1 冻结与打标签
交付的第一步永远是确认你要交付的是哪个提交。不要凭记忆,去看:
git log --oneline -10 git statusgit status这一步不能省。如果工作区有未提交的改动,你得先决定这些改动是丢弃、是提交、还是留着但不影响本次发版。我踩过的坑是:本地改了个配置想临时测试,忘了还原,直接基于当前 HEAD 打了标签。虽然 archive 读的是提交不是工作区,所以包里其实没有那个改动,但我在本地验证的时候用的是带改动的工作区,验证结论和实际交付物对不上,等于白验证。
确认干净之后打标签。前面说过要用附注标签,这里再加一个实用建议:在标签消息里写清楚这次发行改了什么。
git tag -a v1.2.0 -m "Release 1.2.0 - 修复: 批量导入超过 5000 行时超时 - 新增: CSV 导出支持自定义分隔符 - 变更: 默认日志级别从 debug 调整为 info - 破坏性: 移除已废弃的 legacy_parse() 接口"这几行看起来是给自己添麻烦,实际上它会被git show、git tag -n直接读到,生成发布说明的时候能省掉大量回忆工作。而且它是唯一一个和历史绑定的变更说明,比后来写在发布页面上的文字可信度高得多。
如果这次发行需要修 bug 但主干上已经合了不该进这个版本的东西,正确做法是从标签拉一个维护分支:
git switch -c release/1.2 v1.2.0 # 在维护分支上 cherry-pick 修复 git cherry-pick <fix-commit> git tag -a v1.2.1 -m "Release 1.2.1: 修复 ..."不要直接在主干上回滚再打标签,那样会把主干搞乱。
3.2 git archive 的参数拆解与实操
基础用法就一行:
git archive --format=tar.gz --prefix=myproj-1.2.0/ -o myproj-1.2.0.tar.gz v1.2.0参数逐个说清楚,因为每个都有实际影响。
--format=tar.gz指定输出格式。支持的常见值有tar、tar.gz、tgz、zip。选tar.gz的理由是兼容性最好、保留权限位、体积适中。如果你的包要给 Windows 用户直接双击解压,额外再出一个zip,但别用zip替代tar.gz。
--prefix=myproj-1.2.0/给包内所有路径加统一前缀。末尾那个斜杠不能丢,丢了会变成myproj-1.2.0src/main.c这种拼接错误,解压出来是一堆散落文件加一个奇怪名字的目录。这个前缀的价值在于“解压即得一个干净的目录”,对方tar -xzf之后不会把当前目录搞乱。前缀里带版本号是我强烈推荐的,因为不同版本的包解压到同一目录时,带版本号能自动共存。
-o指定输出文件。不加的话内容会直接打到标准输出,那更适合做管道处理。
v1.2.0是树状对象引用,可以是标签、分支、提交哈希,甚至HEAD~3这种相对引用。发行场景下永远用标签。
还有一个常被忽略的参数-9,表示最高压缩级别:
git archive --format=zip -9 --prefix=myproj-1.2.0/ -o myproj-1.2.0.zip v1.2.0注意-9只对 zip 有效,tar.gz 的压缩级别由底层 gzip 决定,git archive没给你这个开关。如果你的包很大想调压缩级别,得走管道:
git archive --format=tar --prefix=myproj-1.2.0/ v1.2.0 | gzip -9n > myproj-1.2.0.tar.gz这里有个非常关键的细节:gzip -n。-n表示不把原始文件名和时间戳写进 gzip 头。如果不加-n,每次打包 gzip 头里的时间戳都不同,导致同样内容打出来的包 sha256 不一致。这就直接破坏了“可复现”这条指标,你想用哈希做校验都做不了。我第一次遇到这个问题时排查了很久,明明内容一模一样,哈希就是对不上,最后才发现是 gzip 头在作祟。
另外注意--format=tar.gz在现代 Git 里本身就做了“不写时间戳”的处理,所以直接用--format=tar.gz是安全的。但如果你手动走管道,就必须自己加-n。这两种写法我都遇到过,建议统一用前者,少一次犯错机会。
还有个实用技巧:想在不落盘的情况下检查包内容,直接用管道:
git archive --format=tar v1.2.0 | tar -tv | wc -l git archive --format=tar v1.2.0 | tar -xO myproj/README.md | head -20-xO表示解压到标准输出而不落盘,看某个文件内容很方便。
3.3 版本号注入:describe 与 export-subst
交付包里的代码需要知道自己的版本号,否则运行时打印日志、上报统计、写缓存目录的时候会很尴尬。有两种注入方式,各有适用场景。
方式一:构建时注入。在打包脚本里先算出描述串,再通过编译参数或者环境变量传给构建过程:
VER=$(git describe --tags --long --dirty --always) echo "版本: $VER" # 示例输出: v1.1.0-23-g3f2a1bcgit describe的输出格式是<最近标签>-<距该标签的提交数>-g<短哈希>。v1.1.0-23-g3f2a1bc读作“基于 v1.1.0,之后又有 23 个提交,当前提交短哈希 3f2a1bc”。--long保证即使当前提交正好就是标签指向的提交,也输出完整格式(v1.2.0-0-gxxxxxxx),这样版本号解析逻辑不用处理两种形态。--dirty在有未提交改动时加后缀,--always保证没有任何标签时也能输出哈希而不是报错。
这个串特别适合做开发构建的版本号。正式发行版则直接用标签名v1.2.0,因为describe输出的-0-gxxxx后缀在发行版里是噪音。
方式二:export-subst 占位符。在仓库里放一个版本文件,内容写上占位符:
版本: $Format:%(describe:tags)$ 提交: $Format:%H$ 日期: $Format:%cI$然后在.gitattributes里声明:
version.txt export-subst打包时git archive会自动把占位符替换成真实值,而且这个替换发生在导出过程中,不改变仓库里的文件内容。也就是说仓库里的version.txt永远带占位符,交付包里才变成实际值。这个设计很干净,不会因为发版而往仓库里提交无意义的改动。
支持的格式占位符不少,常用的有%H(完整哈希)、%h(短哈希)、%cI(提交时间,严格 ISO 格式)、%an(作者名)、%(describe:tags)(describe 结果)。完整列表在gitattributes的文档里有,用之前查一下确认当前 Git 版本支持。
注意:
export-subst只对被跟踪且在归档范围内的文件生效。如果这个文件同时被export-ignore排除了,替换自然不会发生。另外它只在git archive里生效,普通git checkout出来的工作区看到的还是占位符原文,别在本地测试时被这个搞懵。
我个人推荐两个方式一起上:源码里放version.txt走export-subst,构建脚本再读一遍git describe做交叉校验。听起来冗余,但两者对不上就说明有环节出问题了,这个早期预警很值。
3.4 校验清单与变更日志
包打完了,先别急着发。生成校验和:
sha256sum myproj-1.2.0.tar.gz > myproj-1.2.0.tar.gz.sha256发给下游的时候,压缩包和校验和文件一起给。对方执行sha256sum -c myproj-1.2.0.tar.gz.sha256就能验证,一行命令的事。别小看这一步,大文件传输损坏的概率比想象中高,我曾经遇到过一个 80MB 的包在某个环节被截断,解压报错,但因为没有校验和,双方互相怀疑了半天。
变更日志直接从 Git 历史生成,比手写靠谱:
git log --oneline --no-merges v1.1.0..v1.2.0--no-merges过滤掉合并提交,避免日志里一堆“Merge branch xxx”。如果你团队的提交信息规范做得好(比如用约定式提交),还能自动分类:
git log --pretty=format:"%s" --no-merges v1.1.0..v1.2.0 | grep -E '^feat' | sed 's/^feat: /新增: /'这个粗加工的日志不能直接当发布说明用,但能帮你快速回忆起这个版本干了什么,剩下的人工润色十分钟搞定。
最后把所有产物组织成一个目录,结构清晰一点:
release-v1.2.0/ ├── myproj-1.2.0.tar.gz ├── myproj-1.2.0.tar.gz.sha256 ├── myproj-1.2.0.zip ├── CHANGELOG.md └── MANIFEST.txt # 记录 commit hash、构建时间、构建环境MANIFEST.txt是我坚持要加的,内容就几行,但它让“这个包从哪来”这件事变得毫无疑问。
4. 替代解决方案:不是所有场景都该用 archive
git archive是默认答案,但不是唯一答案。下面三种方案在某些场景下明显更优,值得了解。
4.1 git bundle:离线与内网交付
如果对方完全无法访问你的仓库,又需要完整历史(比如要接手维护、要做代码审计、要做git bisect),archive 就不够了。这时候用 bundle:
git bundle create myproj-v1.2.0.bundle --all--all打包所有引用(所有分支、标签)。产物是单个文件,对方执行:
git clone myproj-v1.2.0.bundle myproj就能得到一个和原仓库几乎等价的克隆。
很多时候你不需要全部历史,只想给一条线:
git bundle create myproj-v1.2.0.bundle v1.2.0这样产物里只含v1.2.0可达的对象,体积小很多。但注意:clone 这种单引用 bundle 时,Git 可能会警告“远程 HEAD 指向不存在的引用”,因为它不知道默认该检出哪个分支。解决办法是显式指定:
git clone -b v1.2.0 myproj-v1.2.0.bundle myprojbundle 有两个非常实用的特性。一是可以验证完整性:
git bundle verify myproj-v1.2.0.bundle它会检查包内引用是否指向存在的对象、前置条件是否满足。这个校验比 sha256 更有语义,它能告诉你“这个 bundle 能不能被正常克隆”。
二是可以增量交付。如果对方已经有了v1.1.0,你可以只给他v1.1.0..v1.2.0之间的增量:
git bundle create update-1.1-to-1.2.bundle v1.1.0..v1.2.0对方在已有仓库里执行git pull update-1.1-to-1.2.bundle v1.2.0即可。这个模式在带宽受限的场景下非常香,尤其是接手一个历史很长的大仓库。
bundle 的缺点也明显:它不是普通用户能直接用的东西,需要对方会 Git;而且它不能替代“解压就能编译”的体验。所以我的判断标准是:要历史、要协作,给 bundle;只要源码、要编译,给 archive。
4.2 浅克隆与部分克隆
如果能访问仓库,那就没必要打包,直接让对方拉。但直接clone太重,需要用参数削。
浅克隆只拉最近若干个提交:
git clone --depth 1 --branch v1.2.0 https://example.com/myproj.git--depth 1表示只拉一个提交的深度,--branch可以直接指定标签。这样下来的仓库.git很小,工作区内容完整。适合 CI 构建场景 —— 构建机不需要历史,只需要当前代码。
浅克隆的限制要提前知道:它不能git log完整历史,不能git bisect,某些依赖历史信息的命令会失败。最典型的是git describe,在--depth 1的克隆里通常拿不到标签信息,会退化成只输出哈希。如果你的构建脚本依赖describe生成版本号,浅克隆会让版本号变成一串裸哈希。解决办法是加--tags把标签一起拉下来,或者干脆在 CI 里用环境变量传入版本号,别依赖仓库自身。
部分克隆(也叫带过滤的克隆)是另一种思路,它拉完整历史但延迟下载文件内容:
git clone --filter=blob:none --no-checkout https://example.com/myproj.git--filter=blob:none表示先不下载任何文件内容,只下载提交和树对象。后续git checkout时才按需拉取。这个模式对大仓库的初次克隆体验提升明显,尤其是那种历史里有很多大二进制文件的项目。不过它要求服务端支持过滤能力,用之前要确认。
还有一种更激进的稀疏检出,只把仓库里的某个子目录检出到工作区:
git clone --filter=blob:none --sparse https://example.com/myproj.git cd myproj git sparse-checkout set src/ include/适合巨型单体仓库里只关心一小块的场景。这套组合在超大型项目里几乎是标配,小项目用不上,反而增加理解成本。
4.3 子模块与子树:多仓交付的老大难
只要项目拆成了多个仓库,交付时就会遇到这个问题:主仓库的归档包里不含子模块的内容。
这是git archive的一个硬限制,必须记住。如果你的仓库里用了子模块:
git submodule status # 3f2a1bc... deps/codec (v0.9.1)git archive v1.2.0打出来的包里,deps/codec/只会是一个空目录(或者干脆不存在),因为它只是一个 gitlink 条目。下游解压后编译必然失败,而且报错信息通常很含糊,会让人以为是路径问题。
处理方式有三种,各有代价。
方式一:交付时附上子模块的 bundle 或归档包,在说明文档里写清楚“先解压主包,再把 codec 包解压到 deps/codec/”。这个方式最笨但最可靠,不依赖任何工具特性。
方式二:在 CI 里做“展开”,先git submodule update --init --recursive把内容拉到工作区,再用tar打包整个工作区。但这样就不是git archive了,前面说的那些好处(读对象库、不受工作区污染、export-ignore 过滤)全都没了,得自己写排除规则。我一般不用这个方案,除非确实没别的办法。
方式三:改用子树(subtree)。git subtree会把外部仓库的内容真实地合并进主仓库的提交树里,所以git archive打出来的包天然包含全部内容,没有任何额外步骤。代价是仓库体积变大、历史变复杂、推送回上游需要额外命令。
我的取舍标准是:如果子模块的内容是“编译依赖”,用子树或者干脆把依赖包一起交付;如果子模块的内容是“独立演进、需要双向同步的组件”,保留子模块,在交付流程里显式处理。最怕的是用了子模块但交付流程里没处理,等到下游报错才发现,那时候已经发出去了。
4.4 方案横评表
把上面几种方案拉平了对比,选型时对着看:
| 方案 | 对方需要 Git | 含完整历史 | 包内含子模块 | 体积 | 典型场景 |
|---|---|---|---|---|---|
git archive归档包 | 否 | 否 | 否 | 小 | 源码交付、下游编译 |
git bundle(--all) | 是 | 是 | 否 | 大 | 仓库迁移、离线协作 |
git bundle(指定引用) | 是 | 部分 | 否 | 中 | 增量更新、小范围交付 |
| 浅克隆 | 是 | 否 | 需--recurse | 小 | CI 构建 |
| 部分/稀疏克隆 | 是 | 是(延迟) | 需--recurse | 小 | 巨型仓库局部开发 |
| 子树 | 否(对交付物) | 视主仓而定 | 是(已并入) | 中 | 依赖需随包交付 |
这张表里“包内含子模块”这一列是最容易出事的一列,选型时务必对着它核对一遍。
5. 常见问题与排查实录
下面这些坑,大部分我都亲自踩过,或者帮别人排查过。按问题类型分组,方便对照。
5.1 包内容类问题
包里缺文件。排查顺序是:先确认文件是否被 Git 跟踪(git ls-files <path>),未跟踪的文件git archive一定不会包含,这跟.gitignore无关,纯粹是 archive 只读对象库。再确认是否被export-ignore排除了,用git check-attr export-ignore -- <path>查属性来源,它会告诉你这个属性是在哪个.gitattributes文件里定义的。最后确认路径大小写和符号链接是否造成干扰。
包里多了不该有的文件。最常见的是.github/、.vscode/、测试数据、构建脚本。解决办法只有一个:在.gitattributes里加export-ignore,提交,然后重新打标签。注意顺序 ——属性修改必须进入被打标签的那个提交,否则对已存在的标签无效。这条规则我称之为“标签不可变原则”的直接推论:标签指向的提交是冻结的,它的属性也是冻结的。
$Format$占位符没被替换。三个检查点:文件是否被 Git 跟踪;.gitattributes里是否声明了export-subst;这个.gitattributes是否在被归档的提交里。还有一个隐蔽情况:如果你的.gitattributes里同时给这个文件写了export-ignore,那它压根不会进包,自然谈不上替换。
包里的文件权限丢了。检查归档格式。tar.gz保留权限位,zip在某些解压工具下会丢。如果必须发 zip,在文档里明确写出需要手动chmod +x的脚本列表,或者提供一个Makefile让用户用make而不是直接执行脚本。
5.2 校验与可复现类问题
同样内容打两次包,sha256 不一致。九成是时间戳问题。如果用手动管道git archive | gzip,必须加-n;如果用--format=tar.gz,现代 Git 已经处理好了。还有一个来源是文件系统层面的 mtime —— 如果你不是用git archive,而是先 checkout 再tar整个目录,那 mtime 就是 checkout 时刻的时间,每次都不一样。tar有--mtime参数可以固定,但更彻底的做法是根本不要走工作区。
git describe在 CI 里输出裸哈希。因为 CI 用的是浅克隆,标签不在本地。两条路:一是git fetch --tags或克隆时加--tags,二是干脆别依赖它,在流水线里用变量传入版本号。我倾向后者,让构建脚本对 Git 状态的依赖越少越好,这样本地构建和 CI 构建的行为才一致。
校验和文件本身不可信。如果你的发布页面同时挂包和校验和,而页面被人改了,两个都能被改。真正的信任锚是签名:把校验和用私钥签名,或者把 sha256 写在经过签名的标签说明里。安全要求高的场景,这一步不能省。
标签打错了怎么办。分三种情况。还没推送:git tag -d v1.2.0删了重打,无副作用。已推送但没人用:删除远端标签再重推(这属于改写历史,要先在团队里通知)。已经有人基于它打了包或部署了:绝对不要动它,直接发v1.2.1,在变更日志里说明v1.2.0已被v1.2.1取代。第三条是纪律问题,不是技术问题。
5.3 问题速查表
| 现象 | 最可能的原因 | 快速验证 | 处理 |
|---|---|---|---|
| 包内缺某个文件 | 未跟踪 / 被 export-ignore | git ls-files <path>、git check-attr export-ignore -- <path> | 补跟踪或调整属性 |
| 包内多出无关文件 | 未配置排除规则 | git archive --format=tar <tag> | tar -t | 加export-ignore后重打 |
| 解压后目录结构散乱 | --prefix缺末尾斜杠 | 看包内首层路径 | 补斜杠重打 |
| 两次打包哈希不同 | gzip 时间戳未固定 | 比较gzip -l头部信息 | 用--format=tar.gz或gzip -n |
| 子模块目录为空 | archive 不展开 gitlink | git submodule status | 单独交付或改子树 |
| 版本号显示为裸哈希 | 浅克隆无标签 | git tag -l | --tags或外部传参 |
$Format$原样保留 | 缺export-subst | git check-attr export-subst -- <file> | 补属性后重打标签 |
| zip 解压后脚本不可执行 | zip 权限位支持弱 | ls -l对比 | 改发 tar.gz 或文档说明 |
这张表我建议直接抄进团队 wiki,出问题时先对着它过一遍,比在群里问一圈快得多。
6. 把它塞进流水线:脚本骨架与落地细节
手工打一次包不难,难的是每次都打对。所以真正要落地的形态是一个脚本,放在仓库里,跟着代码一起评审。
6.1 交付脚本骨架
下面这个骨架我在几个项目里用过,逻辑直接可抄,按需改路径和产物名:
#!/usr/bin/env bash set -euo pipefail TAG="${1:?用法: $0 <tag>,例如 v1.2.0}" NAME="myproj" OUT="release-${TAG}" # 1. 基础校验 git rev-parse --verify "${TAG}^{commit}" >/dev/null if [ -n "$(git status --porcelain)" ]; then echo "工作区不干净,请先提交或还原改动" >&2 exit 1 fi # 2. 准备输出目录 rm -rf "${OUT}" && mkdir -p "${OUT}" # 3. 生成归档包(两种格式) git archive --format=tar.gz --prefix="${NAME}-${TAG#v}/" \ -o "${OUT}/${NAME}-${TAG#v}.tar.gz" "${TAG}" git archive --format=zip -9 --prefix="${NAME}-${TAG#v}/" \ -o "${OUT}/${NAME}-${TAG#v}.zip" "${TAG}" # 4. 校验和 ( cd "${OUT}" && sha256sum *.tar.gz *.zip > SHA256SUMS ) # 5. 变更日志 git log --no-merges --pretty=format:"- %s" \ "$(git describe --tags --abbrev=0 "${TAG}^")..${TAG}" \ > "${OUT}/CHANGELOG.md" || true # 6. 交付清单 { echo "项目: ${NAME}" echo "版本: ${TAG}" echo "提交: $(git rev-parse "${TAG}")" echo "标签信息: $(git tag -n1 -l "${TAG}" | cut -d' ' -f2-)" echo "构建时间: $(date -u +%Y-%m-%dT%H:%M:%SZ)" echo "Git 版本: $(git --version)" } > "${OUT}/MANIFEST.txt" echo "完成: ${OUT}"${TAG#v}这个语法是去掉v前缀,得到1.2.0。包名用不带v的版本号是惯例,因为很多包管理器不接受带v的版本号;但标签保留v,因为git describe需要。这个转换看着小事,但如果你忘了转,下游的自动构建脚本可能会解析失败。
set -euo pipefail这一行值得单独说:-e让任何命令失败就退出,-u让引用未定义变量报错,-o pipefail让管道中任一环失败都算失败。没有这三个开关,脚本会在出错后继续往下跑,打出半成品包,比直接失败更危险。很多团队就是在这里翻车的 —— 归档失败了,但脚本继续生成校验和、继续上传,最后发出去一个空包。
6.2 产物命名与归档策略
命名这件事,我见过太多团队栽跟头。核心原则是唯一且可排序。myproj-1.2.0.tar.gz是良构,myproj-final.tar.gz、myproj-最新.tar.gz、myproj-new.tar.gz都是灾难。文件名里必须包含版本号,因为它是最主要的区分维度;不要用日期做版本,因为日期没法表达“谁替代谁”。
排序方面,语义化版本号在字符串排序上有个天然缺陷:1.10.0会排在1.9.0前面。如果你的归档目录靠文件名排序展示,用户会看到错乱的顺序。解决办法是在文件名里用零填充(1.02.00,丑但有效),或者干脆在归档页面读取版本号做数值排序而不依赖文件名。
归档策略上,我建议永久保留所有正式发行版的产物,中间版本(rc、beta)可以设一个保留期。理由很简单:下游可能几年后还在用一个老版本,需要重新下载、需要对比。存储成本相比排查成本微不足道。如果仓库托管服务提供的发布页有数量限制,那就把老产物同步一份到自己的对象存储,同时在发布页保留校验和,这样至少还能验证。
还有一个细节:产物的存放路径不要跟着分支结构走。有些团队把包放在releases/v1.2.0/这种目录里,然后每发一版就提交一次。这会让仓库体积疯狂膨胀,而且二进制文件进 Git 是明显的反模式。产物应该放在构建产物存储里,仓库里只保留生成它的脚本和配置。
最后说一个我个人的做法。我会在每次发版后,把MANIFEST.txt和SHA256SUMS的内容贴一份到发布说明的末尾,同时把git describe --tags --long的结果也写上。这个习惯看起来啰嗦,但它让我在半年后回看某个版本的交付记录时,能立刻判断出“这个包是从哪个提交来的、当时用的是哪个 Git 版本”。有一次下游报了个很怪的解包错误,我就是靠MANIFEST.txt里记录的 Git 版本号,发现对方用的解压工具不认那个版本的 tar 变体,五分钟定位问题。
这套流程跑顺之后,一次发版的操作时间大概就是“打标签 + 跑脚本 + 上传”三分钟,剩下的时间可以放在写发布说明和回答下游问题上。真正花时间的是前期把.gitattributes规则和脚本调对,这部分一次性投入,后面每次发版都在收利息。