如何运用git archive技巧高效导出项目文件？

本文共计1004个文字，预计阅读时间需要5分钟。

直接运行以下命令不会生成文件，而是将二进制zip流输出到终端：

• 必须显式用 --output=xxx.zip 指定文件名，或用 shell 重定向：git archive --format=zip HEAD > out.zip
• 如果只写 --output=out.zip 却漏掉 --format，Git 会尝试从文件后缀推断格式；但 .zip 推断成功，.tar.gz 也可能失败（某些旧 Git 版本不支持自动识别双后缀）
• Windows 上用重定向生成的 .zip，部分解压工具（如系统自带的“压缩文件夹”）可能打不开——这不是损坏，是 zip 标准兼容性问题，换 7-Zip 或 WSL 的 unzip 就能正常解压

导出子目录时路径末尾必须加斜杠，否则报错

git archive 对路径参数极其严格：要导出 src/frontend 目录下所有内容，命令里必须写成 src/frontend/（带末尾斜杠），写成 src/frontend（不带斜杠）会直接报错 fatal: Not a valid object name src/frontend。

• 原因：Git 把不带斜杠的 src/frontend 当作一个文件名去查索引，而它实际是个目录；加斜杠后 Git 才识别为路径前缀匹配
• 常见场景：CI 脚本中动态拼接路径，容易漏掉斜杠；建议统一用 "$DIR/" 字符串拼接，避免条件分支遗漏
• 验证方式：先用 git ls-tree -d HEAD src/frontend/ 确认该路径存在且被 Git 跟踪

想打包 .gitignore 里的文件（比如 config.example），得先 git add -f

git archive 只打包「已进入索引（staging）」的文件，完全无视工作区里未 git add 的内容——哪怕文件真实存在、也没被 .gitignore 拦截，只要没 add 过，就不会出现在归档里。

• 典型需求：交付包里需要 config.example，但它在 .gitignore 里。正确做法是：git add -f config.example，然后 git commit（或直接对这个 commit 执行 archive）
• Git 2.39+ 可用 --add-file=.gitignore 显式加入单个未跟踪文件，但注意：它不能绕过 .gitignore 规则，仅适用于本机工作区存在的文件
• 不要用 git checkout + tar 组合来“绕过”——这会把未跟踪文件、临时文件甚至编辑器备份（如 *~）一并打包，失去 archive 的干净性优势

远程仓库归档需服务端支持，GitHub 默认关闭 --remote

git archive --remote=git@github.com:user/repo.git HEAD 听起来很美，但 GitHub、GitLab 等主流平台默认禁用 git-upload-archive 服务，执行会报错 fatal: upload-archive not enabled。

• 本地自建 Git 服务器可启用，但公有云平台几乎都不开——别在自动化脚本里硬写这个参数，CI 失败率极高
• 替代方案：用 GitHub API 下载 release assets（如果有发布），或用 curl -L https://github.com/user/repo/archive/refs/tags/v1.2.0.tar.gz 直接拉取 GitHub 自动生成的归档
• 真正可靠的远程归档，只适用于你完全控制的 Git 服务（如 Gitea + 配置 [uploadarchive]）

最易被忽略的一点：archive 的时间戳来自 commit 对象本身，不是打包时刻。如果你用 git archive 导出一个一年前的 tag，解压后所有文件的修改时间都是一年前的 commit time——CI 构建工具依赖 mtime 做增量编译时，这点会引发意外行为。