如何配置Composer排除自动加载某些以_开头的文件？

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

Composer 没有全局排除文件的开启，所谓的排除，指的是控制哪些路径不被自动加载。本质上是控制哪些路径被自动加载（autoload）—— 未声明的，自然不加载；声明了但想筛选掉，需查看类型选择配置项。

autoload.exclude 只在 Composer 5.0+ 有效，且仅限 PSR-4/PSR-0

这个字段常被误以为是通用排除机制，其实它只对 psr-4 和 psr-0 生效，完全不管 classmap 或 files。

• 检查版本：composer --version，低于 5.0.0 写了也白写
• 路径必须相对 composer.json，比如想排除 tests/Stub/，就得写 "tests/Stub/"（末尾斜杠推荐加）
• 不支持通配符："tests/**/*.php" 或 "*.test.php" 都无效，只能写具体目录或文件路径
• 改完必须运行 composer dump-autoload，否则 vendor/autoload.php 不更新

exclude-from-classmap 只对 classmap 生效，别指望它拦 PSR-4 类

如果你的 composer.json 里只有 "psr-4": {"App\": "src/"}，那加 exclude-from-classmap 基本没反应 —— 它压根不参与 PSR-4 加载流程。

• 必须显式声明 classmap，例如："classmap": ["src/", "lib/"]
• exclude-from-classmap 路径也相对项目根，支持 *（如 "legacy/*"），Composer 2.2+ 起支持 ** 递归匹配
• 常见错误：写了 "tests/" 却发现 TestsFooTest 还能加载 —— 因为它走的是 PSR-4 映射，根本没进 classmap 表
• 改完同样要 composer dump-autoload，否则 vendor/composer/autoload_classmap.php 不变

autoload-dev 不是排除，而是环境隔离

autoload-dev 里的规则（比如 "App\Tests\": "tests/"）不会让 tests/ 在生产环境“消失”，它只决定：当运行 composer install --no-dev 时，这些命名空间是否注册进自动加载器。

• --no-dev 不删文件，只跳过 autoload-dev 的加载注册
• 如果 tests/ 同时被 psr-4 主映射覆盖（如 "App\": "src/" 包含了 src/Tests/），那它照样被加载
• 真正安全的做法是：把测试类挪到独立目录（如 tests/），并只在 autoload-dev 中映射，主 autoload 里完全不提它
• 混在 src/ 里的测试类最难处理 —— 此时 exclude-from-classmap 是唯一能从 classmap 表里剔除它们的手段

想让文件彻底不出现在生产包里？靠 .gitattributes，不是 composer.json

archive.exclude 只影响 composer archive 或 Packagist 构建的分发包，对 composer install 完全无感；而 GitHub/GitLab 的 Download ZIP 默认用 git archive 打包，只认 .gitattributes。

• 在项目根目录建 .gitattributes，内容如：/tests export-ignore
• 路径开头必须加 /，否则 tests 会误删 mytests.php
• export-ignore 是 Git 原生命令，所有基于 git archive 的行为（Packagist、GitHub Releases、composer archive）都遵守
• composer.json 里的 "archive": {"exclude": ["/tests"]} 对 GitHub 手动下载 ZIP 无效

最容易被忽略的点：同一个文件可能被多个 autoload 机制兜底加载 —— 比如你用 exclude-from-classmap 排除了 tests/，但它又被 psr-4 主映射覆盖，或者被硬编码的 require 加载，那排除就形同虚设。排查时得逐层确认加载链，而不是只盯一个配置项。