悠悠楠杉
网站页面
如何使用ComposerArchive命令打包项目
12/15
![]()
在现代 PHP 开发中，Composer 不仅是依赖管理的标配工具，还内置了一些实用功能来辅助项目的构建与发布。其中，composer archive 命令就是一个容易被忽视却极为实用的功能——它允许开发者将当前项目或指定版本打包成归档文件（如 tar 或 zip），非常适合用于部署、备份或分发独立的应用程序包。
要理解 composer archive 的价值，我们先来看一个常见的开发场景：你完成了一个命令行工具或小型 Web 应用，希望将其打包发送给客户或部署到生产服务器，但又不想通过 Git 克隆或手动复制文件。此时，手动整理代码、排除测试文件和开发配置既耗时又容易出错。而 composer archive 正是为此类需求设计的自动化解决方案。
基本用法
最简单的 archive 命令只需在项目根目录下执行：
bash
composer archive
这条命令会根据 composer.json 中定义的 name 和当前版本号（version）生成一个归档文件，例如 myapp-1.0.0.tar。默认格式是 tar，你也可以通过 --format 参数指定其他格式：
bash
composer archive --format=zip
这将生成一个 .zip 文件，更适合在 Windows 环境中使用。
你还可以指定打包的版本，而不是当前本地版本：
bash
composer archive 1.2.0 --format=tar
这在你需要回溯打包历史版本时非常有用，前提是该版本已在 composer.json 中声明或可通过版本控制系统获取。
自定义输出路径与文件名
默认情况下，归档文件会生成在当前目录下。你可以使用 --dir 指定输出目录：
bash
composer archive --format=zip --dir=build/
此外，通过 --file 参数可以自定义文件名：
bash
composer archive --file=my-release-package.zip
结合这两个选项，你可以构建出清晰的构建流程：
bash
mkdir -p dist
composer archive --format=zip --file=dist/app-v$(grep '"version"' composer.json | cut -d'"' -f4).zip
这段脚本会自动提取 composer.json 中的版本号，并生成类似 dist/app-v1.3.5.zip 的文件，便于版本追踪。
排除开发文件：利用 .gitattributes
composer archive 并不会盲目打包所有文件。它会参考 .gitattributes 文件中的 export-ignore 标记，自动忽略不应包含在发布包中的内容。例如，在你的项目中添加 .gitattributes：
/tests export-ignore
/docs export-ignore
.docker export-ignore
.env.example export-ignore
composer.lock export-ignore
这样，当你运行 composer archive 时，这些标记为 export-ignore 的目录和文件将不会被打包进去。这对于确保发布包干净、安全至关重要。
如果你没有使用 Git，Composer 也会尝试根据标准规则排除常见开发文件，但强烈建议使用 .gitattributes 来精确控制打包内容。
实际应用场景
一个典型的使用场景是 CI/CD 流水线中的自动打包。例如，在 GitHub Actions 中：
yaml
- name: Build release package
run: |
mkdir -p dist
composer archive --format=zip --file=dist/app-${{ github.ref_name }}.zip
if: startsWith(github.ref, 'refs/tags/')
当打上 Git tag 时，系统会自动触发打包流程，并生成对应版本的 ZIP 文件，可用于后续上传至发布页面或内部服务器。
另一个场景是分发闭源 PHP 工具。你可以将核心逻辑打包并通过 phar 配合 archive 构建基础包，再结合其他工具生成可执行的 PHAR 文件。
注意事项
尽管 composer archive 功能强大，但也有一些限制需要注意。首先，它只能打包本地已存在的版本，不能远程拉取未克隆的标签。其次，如果项目未设置版本号（如 dev-main），打包可能失败或生成不规范的文件名，因此建议始终在 composer.json 中明确定义版本。
另外，archive 命令不会自动安装依赖或执行构建脚本。如果你的项目需要编译资产（如前端资源），应在打包前手动运行 npm run build 或类似的命令。
总之，composer archive 是一个轻量但高效的工具，尤其适合中小型项目的快速打包与发布。合理使用它，配合 .gitattributes 和自动化脚本，可以显著提升部署效率，减少人为错误。对于追求简洁发布流程的 PHP 开发者来说，掌握这一命令无疑是值得的。
