git archive必须指定--output或重定向，否则二进制zip流直接输出到终端导致乱码；它只打包已add进索引的文件，不依赖工作区，支持按commit/tag/分支及子目录打包，并自动忽略.gitignore项。
git archive 必须指定 --output 或重定向，否则输出到 stdout 乱码
直接运行 git archive --format=zip HEAD 不会生成文件，而是把二进制 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 做增量编译时，这点会引发意外行为。
