必须在主项目composer.json中显式声明本地包的autoload规则(如"psr-4": {"MyUtils": "packages/my-utils/src/"}),并执行composer install --optimize-autoloader才能使其参与优化;仅配path仓库不触发autoload优化。

composer.json 里配本地包(如 path 类型 repository)本身不会自动触发类加载优化;真正起作用的是你**怎么声明它的 autoload 规则**,以及**是否在安装时启用优化开关**。不手动干预,本地包的类照样走 PSR-4 实时查找,哪怕它就在你项目目录里。
本地包的 autoload 必须显式声明在根 composer.json 中
Composer 不会自动读取本地包 composer.json 的 autoload 配置——除非你把它作为正式依赖通过 require 引入,并且该包已发布到 packagist 或配置了 path repo。但即使如此,它的 autoload 规则默认仍被忽略。
正确做法是:把本地包的命名空间和路径,直接写进你主项目的 composer.json 的 autoload 或 autoload-dev 里。
- 若本地包路径为
packages/my-utils,命名空间为MyUtils\,则加:
"autoload": {
"psr-4": {
"MyUtils\": "packages/my-utils/src/"
}
}
- 不要指望
"type": "path"的 repository 能“透传” autoload;它只影响安装位置,不影响加载逻辑 - 如果本地包没用标准 PSR-4 结构(比如只有
functions.php),就得走files字段,且路径必须相对于主项目根目录:"files": ["packages/my-utils/helpers.php"]
dump-autoload -o 对本地包无效,必须用 install/update
composer dump-autoload -o 不会扫描本地包路径,也不会把它们塞进 autoload_classmap.php。它只处理当前项目 autoload 字段里声明的路径。
要让本地包参与 classmap 优化,必须满足两个条件:
- 它的路径已声明在主项目的
autoload.classmap或autoload.psrr-4中 - 执行的是
composer install --optimize-autoloader或composer update --optimize-autoloader,而不是dump-autoload
例如,你想强制扫描 packages/my-utils 下所有类:
"autoload": {
"classmap": ["packages/my-utils/"]
}
然后运行:composer install --no-dev --optimize-autoloader —— 这才会真正生成包含它的 autoload_classmap.php。
本地包 + classmap-authoritative 容易报 Class not found
一旦开了 --classmap-authoritative,Composer 就彻底放弃文件系统 fallback。此时如果本地包里有以下情况,必报错:
使用 template.yaml 定义创建 Spotify Backstage 软件模板,包含 Scaffolder 操作,包括 fetch:template、publish:github 和 catalog:register。通过其 REST API 管理 Backstage 软件目录。
- 类文件名与类名大小写不一致(
User.php里定义class user) - 用了下划线命名(
My_Controller.php)或点号(Config.v1.php),这类文件默认不被 classmap 扫描器识别 - 命名空间声明漏了结尾反斜杠(写成
"MyUtils": "packages/my-utils/src/"而非"MyUtils\": "packages/my-utils/src/") - 路径存在但为空,或被
.gitignore排除(classmap 扫描器跳过被 ignore 的目录)
验证方法很简单:打开 vendor/composer/autoload_classmap.php,搜 MyUtils\,看对应类是否在里面、路径是否可读。
开发中频繁改本地包,别开 optimize-autoloader
本地包常处于活跃开发状态:改类名、挪目录、新增文件。而 --optimize-autoloader 生成的 classmap 是静态快照,不会自动感知变更。
你每次改完,都得手动跑:
composer dump-autoload -a && composer install --no-dev --optimize-autoloader
否则新类永远进不了 classmap,开了 --classmap-authoritative 就直接挂掉。
更务实的做法是:开发阶段关掉所有优化,只在 CI 构建或部署前统一生成一次权威 classmap,并确保本地包代码已冻结、路径稳定、命名规范。










