git archive 是导出指定版本代码最干净、最可靠的方式，不污染工作区、不依赖本地修改、自动排除 .git 目录和未跟踪文件；必须指定 --format 和 --output 才能生成可用文件，漏掉任一参数将导致输出异常或解压失败。
git archive 是导出指定版本代码最干净、最可靠的方式，不污染工作区、不依赖本地修改、自动排除 .git 目录和未跟踪文件。
git archive 必须指定 --format 和 --output 才能生成可用文件
漏掉 --output 会导致输出直接刷到终端（尤其是 --format=tar 默认行为），看起来像乱码；漏掉 --format 则默认用 tar 流，Windows 上解压常失败。
-
--format=zip最通用，但 Windows 下中文路径可能乱码（第三方解压工具兼容性差） -
--format=tar.gz或--format=tar更稳定，Linux/macOS 原生支持，WSL 或 7-Zip 也能正常处理 -
--output（或简写-o）必须是完整路径，比如./dist/v2.1.0.zip，相对路径也行，但别省略 - 不加
-v参数时静默执行，加了会列出所有打包文件，适合调试是否漏了关键文件
导出时文件缺失？检查 .gitignore 和索引状态
git archive 只打包 Git 索引（staging）里已跟踪的文件，.gitignore 规则生效，且完全无视工作区里“存在但没 git add”的文件——这不是 bug，是设计如此。
- 常见现象：
config.example或.env.example在磁盘上，但 zip 里没有 - 解决方法：先
git add -f config.example强制加入索引，再 commit 或直接引用该 commit 打包 - 不想永久跟踪？可在打包前临时
git add -f，打包完git reset HEAD config.example - 用
git ls-files --cached查看当前索引有哪些文件，比猜更准
如何只打包子目录或加统一前缀？
交付包解压后文件散在根目录很麻烦，--prefix 和路径限定是刚需。
-
--prefix=myproject-v1.2/：解压后所有文件都在myproject-v1.2/子目录下，避免污染当前目录 - 只打包
src/和public/：git archive --format=zip -o app.zip HEAD src public - 路径必须是仓库内真实存在的目录名，不能用通配符（如
**/*.js不支持） - 想排除某些目录？靠
.gitattributes文件 +export-ignore，例如写/node_modules export-ignore
Windows 中文文件名乱码怎么办？
不是编码设置问题，而是 zip 格式对 UTF-8 路径支持不一致。Git 本身不修复，得绕开。
- 首选方案：改用
--format=tar.gz，Linux/macOS 和 WSL 解压无压力，Windows 用户用 7-Zip 也能正确识别中文 - 次选：加
--worktree-attributes，配合.gitattributes里的export-subst做变量替换（适合需要注入版本号的场景） - 不推荐：试图用
iconv或重命名文件来“适配”，维护成本高，CI 流水线容易崩 - 验证方式：用
unzip -l xxx.zip | head看文件名是否可读，比双击解压更可靠
真正容易被忽略的是：git archive 的输入源永远是 Git 对象数据库，不是你当前看到的文件。哪怕工作区有未提交修改、甚至删了某个 tracked 文件，只要没 git commit，archive 就不会反映它——这既是安全点，也是排查“为什么打包结果不对”的第一检查项。
