Composer archive如何打包_Composer压缩项目必备指令

Composer 没有内置 archive 命令，执行必报错“Command 'archive' is not defined”；真正可靠方式是用 git archive 配合 .gitattributes 排除文件，或封装 PHP 脚本调用 ZipArchive 类打包，并务必提前运行 composer install --no-dev --optimize-autoloader。

如果你在终端里满怀期待地敲下 composer archive，等着它帮你打包项目，那么接下来看到的错误信息恐怕会让你瞬间清醒：Command "archive" is not defined。没错，Composer 压根就没有内置的 archive 命令。市面上那些声称“一条命令就能打包”的教程，要么是基于早已过时的第三方插件，要么就是混淆了 Git 命令或自定义脚本。

为什么 composer archive 在你机器上根本不存在

这个问题的根源很简单：官方 Composer 二进制程序中，从来就没有实现过所谓的 archive 命令。你既无法在 composer list 的输出里找到它，官方文档里也查无此令，甚至连源码里都找不到对应的类。那些描述得煞有介事、支持 --format、--dir 等参数的用法，其实都来自两个早已失效的源头：

• 早期的第三方插件（比如 composer-archive-plugin），最后一次更新停留在 2018 年，不仅完全不兼容 Composer 2.x，而且早已无人维护。
• 部分开发者将 git archive 命令误记成了 Composer 的原生命令（实际上，git archive --format=zip -o app.zip HEAD 才是真正可用的命令）。

所以，当你执行 composer archive 时，Shell 只是在寻找一个从未被注册过的命令——失败是必然的，这无关配置，也无关权限。

真正能落地的打包方式：用 git archive + .gitattributes

如果你的项目托管在 Git 仓库中（绝大多数情况都是如此），那么最干净、可追溯且无需额外依赖的打包路径，就是使用 Git 自身的归档功能。它天然地只打包那些被 Git 跟踪的文件，自动忽略 .git/、vendor/、node_modules/ 等未被追踪的内容。

具体操作步骤可以这样来：

• 在项目根目录创建一个 .gitattributes 文件，明确写入需要排除的路径，例如：

  tests/** export-ignore
  docs/** export-ignore
  .env export-ignore
  *.log export-ignore

• 确保当前工作区是干净的（运行 git status 没有未提交的变更），然后打一个标签（比如 v1.2.0），或者确认你要打包的那个提交已经推送到了远程仓库。
• 运行打包命令：

  git archive --format=zip --output=release-1.2.0.zip v1.2.0

这样生成的 zip 包不会包含 vendor/ 目录。部署时，需要在目标环境中运行 composer install --no-dev --optimize-autoloader 来补齐依赖。

需要连 vendor/ 一起打包？别用 scripts 写 zip -r

很多团队希望实现“一键打包包含 vendor 的完整可运行包”，于是习惯性地在 composer.json 的 scripts 字段里塞入类似 zip -r deploy.zip . -x "node_modules/*" 的命令。这种做法在 CI/CD 环境或 Windows 系统上极易失败：

• zip 命令在 Windows 的 cmd 中并不可用；即便在 Git Bash 或 WSL 下，其参数语法也可能与 macOS/Linux 不完全兼容（比如 -x 排除语法）。
• scripts 在执行时不会加载项目的自动加载器，也无法进行复杂的条件判断（例如“只有打标签时才执行打包”）。
• 缺乏错误捕获机制：如果某次 zip 命令因权限等问题失败，整个构建流程可能会静默跳过，直到部署时才发现 Class not found 的错误。

更可靠的做法是封装一个独立的 PHP 脚本，例如 scripts/archive.php。在脚本开头引入 require __DIR__.'/../vendor/autoload.php';，然后使用 PHP 内置的 ZipArchive 类，通过 addFile() 或 addGlob() 方法逐个添加文件，显式控制哪些路径需要加入压缩包（比如 vendor/），哪些需要跳过（比如 .git/、tests/）。最后调用 $zip->close() 并检查其返回值。

打包前必须完成的三件事，否则部署必出问题

无论你使用 git archive 还是自定义的 PHP 脚本生成 zip 包，如果在打包前跳过了以下任何一个环节，上线后大概率会遇到麻烦：

• 优化自动加载映射：运行 composer dump-autoload --optimize --no-dev。这会生成高效的 autoload_classmap.php 文件，避免部署时因类映射缺失而出现 Class not found 错误。
• 处理环境配置文件：确保 .env 文件不随包发布，或者至少不包含生产环境的敏感值。可以在 .gitattributes 中加入 .env export-ignore 来排除它。部署后应基于 .env.example 重新生成。
• 验证项目与代码：执行 composer validate 来检查 composer.json 的合法性，同时用 php -l 检查关键文件的语法，确保压缩包里不会塞进有语法解析错误的代码。

其中，自动加载优化是最容易被忽略的一环。不少人以为只要 vendor/ 目录里有 autoload 文件就万事大吉，但如果没运行过 dump-autoload --optimize，项目在未启用 OPcache 的环境里会反复扫描 psr-4 映射，不仅导致应用启动变慢，还可能遗漏某些类。