如何通过Composer发布压缩版项目包？

本文共计850个文字，预计阅读时间需要4分钟。

它不打包整个项目目录，而是根据`composer.json`中定义的包结构生成归档：

关键点在于：归档内容由 composer.json 驱动，不是当前工作目录的快照。所以执行前必须确保：

• composer.json 的 name 和 version 字段已正确填写（如 "myorg/myapp": "1.2.0"）
• 若依赖未安装，vendor/ 不会出现在归档里——这没问题，因为 archive 本就不打包依赖
• 想排除某些文件？在 composer.json 中加 "archive": {"exclude": ["docs/", "scripts/deploy.sh"]}

为什么 --format=tar 生成的是 .tar 而不是 .tar.gz？

composer archive 的 --format=tar 只调用系统 tar 命令做归档，不触发 gzip 压缩；同理 --format=zip 调用 zip 工具，也不额外压缩。

如果你需要 .tar.gz 或 .zip 以外的格式（比如 .tar.xz），得手动后处理：

• 生成 tar 包后运行：gzip project-name-1.2.0.tar → 得到 project-name-1.2.0.tar.gz
• 或用 xz：xz project-name-1.2.0.tar → 得到 project-name-1.2.0.tar.xz
• 注意：远程包（如 monolog/monolog）打包时也遵循同样规则，不会自动加压缩层

打包远程包时 --version 不生效？检查三件事

执行 composer archive monolog/monolog --version=2.0.0 --format=zip 却得到 3.0.0 版本的包，大概率是以下原因之一：

• --version 值未被 Packagist 索引：该版本可能尚未发布，或 tag 名不规范（如 v2.0.0 vs 2.0.0），Composer 会 fallback 到最新稳定版
• 本地有缓存：运行 composer clear-cache 再试
• 包使用了 VCS 仓库而非 dist 发布：某些私有包或 dev 分支未打正式 tag，--version 参数会被忽略，实际拉取的是 dev-main 或 dev-master

验证方式：先跑 composer show monolog/monolog 2.0.0，看是否能查到该版本及对应 dist URL。

输出文件名和路径为什么总不对？

默认行为是生成 dist/ 目录（不存在则自动创建），文件名格式固定为 {vendor}-{package}-{version}.{format}，例如 acme-utils-1.2.0.zip。但这个逻辑受两个隐藏因素影响：

• --file 参数只控制主文件名，**不覆盖扩展名**：--file my-release + --format zip → my-release.zip，不是 my-release
• --dir 必须是**已存在的可写目录**：如果写 --dir ./output 但 output/ 不存在，命令会静默失败（无报错），直接退回到当前目录
• Windows 用户注意路径分隔符：用 --dir "C:/releases"，别用反斜杠 \，否则可能被解析为转义字符

最稳妥的做法：提前 mkdir -p dist 或 mkdir dist，再执行 composer archive --format=zip --dir=dist。