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 时，系统只是在寻找一个未注册的命令，失败是必然结果，与配置或权限无关。

可靠的打包方法：使用 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 映射，导致应用启动变慢，甚至可能遗漏某些类。