Composer archive命令利用 ignore 语法实现源代码与资源的差异化打包

先说几个关于 composer archive 的关键判断。这个命令在实际项目中踩坑的概率不低，尤其是当你要用它来做部署包或分发包的时候。很多人一上来就composer archive，结果发现包体积异常大、漏了不该漏的、或者塞了不该塞的——然后开始怀疑人生。

这篇文章就是为了把这些问题彻底讲清楚，从一个实际工作流出发，把打包时那几个最容易被误解的细节掰开揉碎。

archive 命令默认不读 .gitignore，必须显式启用 --ignore

先说第一个核心误区：composer archive 默认完全无视 .gitignore。你没看错，它根本不看 Git 的配置文件。不少人以为“项目都用了 .gitignore，那打包时这些文件肯定自动排除”，但实际完全不是这么回事。

不加 --ignore 参数时，所有源码目录下的文件——包括 node_modules/、tests/、.env 这些你肯定不想带进生产包的东西——都会被一股脑儿打进压缩包。真正能让 Composer 识别并应用 .gitignore 规则的，是 --ignore 这个开关。

实践中的经验是这样：

• 打包前一定要记住加 --ignore。比如 composer archive --format=zip --file=dist.zip --ignore
• 注意，--ignore 只认项目根目录下的 .gitignore，子目录中的 .gitignore 文件对它无效
• 如果项目压根没用 Git，或者你需要一套和 .gitignore 不一样的排除规则，可以改用 --exclude 手动指定路径，比如 --exclude="tests/" --exclude=".env"

ignore 规则对资源文件（如 assets/、public/）的处理很“严格”

接下来要说的这个问题，才是真正容易让人抓狂的地方。.gitignore 里写 /vendor/ 或者 *.log 这类规则通常没问题，但一旦涉及资源目录，比如 assets/ 或 public/*，就很可能好心办坏事——把本该打包进去的前端资源给误杀了。

原因在于 composer archive --ignore 的路径匹配方式跟 Git 不一样。它按行逐条匹配路径，不支持通配符的上下文感知，而是把 assets/ 当作从包根开始的绝对路径前缀来解读。换句话说，Git 里 assets/ 的意思是“工作区任意位置的 assets 目录”，而在 Composer 这里，它变成了“包根目录下的 assets”。如果你的 .gitignore 写的是 assets/，那 Composer 就会把包根目录下的整个 assets/ 全盘排除——而不是 Git 那种“只排除根目录下的 assets”。

常见翻车现场：

• assets/js/app.js 被意外排除，就因为 .gitignore 里有一条 assets/
• public/index.php 丢失，因为 .gitignore 中写的是 public/*（实际应该写 public/*.tmp 这类更精确的规则）
• 想保留 public/images/ 但排除 public/images/temp/——这种需求单靠 .gitignore 几乎无法安全表达

vendor 目录是否打包取决于 --no-dev 和 --ignore 的组合逻辑

关于 vendor/ 的处理，又是另一层复杂性。composer archive 默认情况下不打包 vendor/，哪怕你没有加 --ignore。但它到底会不会跳过 vendor/，其实取决于两个独立条件：

第一，--no-dev 控制的是 dev-dependencies 是否安装，这个对打包行为本身没有直接影响；第二，--ignore 是否启用，以及 .gitignore 里有没有写 /vendor。换句话说，如果 .gitignore 里漏掉了 /vendor，同时你又没加 --ignore，那 vendor/ 就会被原样打进 zip 包——这通常不是你想要的。

标准做法是：

• 生产环境打包时，一律使用 --ignore --no-dev 组合
• 确认 .gitignore 包含 /vendor，注意开头的 / 很重要，它避免了误伤像 myvendor/ 这样的目录
• 不要依赖 composer.json 里的 archive-patterns 字段——它只影响 composer install 时对 vendor 的提取，跟 archive 命令没有任何关系

打包后校验缺失文件比预设规则更可靠

最后一个建议，可能也是最务实的。不管你多小心地编写 .gitignore，总会有漏网之鱼——新添加的调试文件（比如 dump.php）、IDE 临时文件（.idea/）、CI 生成物（coverage/），这些都容易在忙乱中被忽略。与其反复调整 ignore 规则来追求“完美”，不如换一种思路：打完包之后，立刻解压检查，或者用 unzip -l dist.zip | grep -E "(test|.env|.log)" 这类命令快速扫描一下包里有没有不该出现的敏感路径。

另外还有几个容易被忽视的点：

• composer archive 不会校验文件权限。在 Linux 下执行过 chmod +x 的脚本，打进 zip 后如果在 Windows 环境解压，执行位会丢失
• --format=tar 生成的 tar 包默认不压缩，体积比 zip 大得多。别因为“没报错”就想当然认为 tar 包也是被压缩过的
• 如果项目全局配置了 composer config --global archive-format zip，这个全局设置会覆盖你在命令行中指定的 --format=tar，导致你真的用了 tar 参数却拿到一个 zip

说到底，composer archive 是个好工具，但前提是你要清楚它跟 .gitignore 之间那种微妙的关系。把上面这几条理清楚，至少能省下不少排查时间。