如何在 composer.json 中配置 archive.exclude 来打包时忽略特定文件？

Composer 2.2+ 支持在 composer.json 根级配置 "archive": {"exclude": [...]}, 用于 composer archive 命令排除文件；旧版不支持，无效字段会被静默忽略。

在 composer.json 中，没有 archive.exclude 这个配置项。这是常见误解——Composer 官方并不支持 archive.exclude 或类似字段来控制 composer archive（打包）时的文件排除。

真正可用、且被 Composer 原生支持的方式是使用 archive → exclude（注意：是顶层 archive 对象下的 exclude 数组），但前提是你要用的是 Composer 2.2+，并且这个功能仅在运行 composer archive 命令时生效（不是 install/update）。

✅ 正确配置方式（Composer 2.2+）

在 composer.json 的根级别添加 archive 字段：

{
    "name": "your/vendor",
    "version": "1.0.0",
    "archive": {
        "exclude": [
            "/tests/",
            "/Tests/",
            "/phpunit.xml",
            "/phpstan.neon",
            "/.gitignore",
            "/.editorconfig",
            "/docker/",
            "/*.md",
            "!/README.md"
        ]
    }
}

? 说明：

• exclude 是一个字符串数组，每项是路径匹配模式。
• 支持通配符 * 和前导 / 表示从包根开始匹配。
• ! 开头表示白名单反排除（即即使父目录被排除，该文件仍保留），如 "!/README.md"。
• 路径区分大小写（尤其在 Linux/macOS 环境）。
• 不支持正则，只支持简单 glob 风格（类似 .gitignore 规则）。

⚠️ 注意：此配置不会影响 composer install 下载的 vendor 包内容，只影响你执行 composer archive 打出的 zip/tar 包。

✅ 如何生成归档包？

确保你已安装 Composer，并在项目根目录运行：

composer archive --format=zip --file=my-package-1.0.0

它会根据 archive.exclude 规则自动过滤文件。

❌ 常见错误写法（无效！）

// 错误：不存在的字段名
"archive.exclude": [...]

// 错误：放在 config 或 scripts 下
"config": {
    "archive.exclude": [...]
}

// 错误：旧版 Composer（<2.2）不识别该配置

如果你用的是 Composer 2.1 或更早版本，archive.exclude 完全不生效，会静默忽略。

检查版本：

composer --version

升级 Composer（推荐）：

composer self-update

✅ 替代方案（兼容旧版或更精细控制）

如果不能升级 Composer，或需要更强控制力，可改用：

• .gitattributes 文件（推荐）
  Composer 在 archive 时默认读取 .gitattributes 中的 export-ignore 规则：

  /tests/ export-ignore
  /phpunit.xml export-ignore
  .gitignore export-ignore
  README.md export-ignore
  !/README.md export-ignore  # 不支持反排除？实际不生效，慎用白名单

  ✅ 兼容所有 Composer 版本，也适用于 Git 自带的 git archive。

• 自定义脚本 + zip/tar 命令
  在 scripts 中定义打包命令，用 shell 工具手动 exclude。

基本上就这些。核心记住一点：archive.exclude 是 Composer 2.2+ 的特性，必须写在 composer.json 根层级的 archive 对象里，不是随便起个名字就行。