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 映射，不仅导致应用启动变慢，还可能遗漏某些类。
