多个项目共用vendor目录会导致autoload_psr4.php混杂不同项目的命名空间映射，PSR-4仅按前缀匹配而无法区分来源，且files类型加载会引发同名函数重复声明错误；正确做法是各项目独立vendor，通过path仓库+主项目autoload配置统一管理共享包。
共享依赖的自动加载不能靠“共用 vendor 目录”来解决，必须让每个项目独立生成 autoload 文件，但统一声明命名空间映射规则。
为什么直接 symlink vendor 或共享 vendor/autoload.php 会出错
多个项目共用同一份 vendor/ 时，autoload_psr4.php 是按各自 composer.json 的 autoload 块生成的。一旦两个服务分别声明了 "AppA\": "src-a/" 和 "AppB\": "src-b/"，合并后的 autoload 文件会同时注册两者，运行时无法区分该加载哪个路径下的类——PSR-4 匹配只看命名空间前缀，不看来源项目。
更隐蔽的问题是 files 类型加载（比如全局 helper 函数），它不走命名空间隔离，同名函数在多个服务间会相互覆盖，报 Cannot redeclare xxx() 错误。
常见错误现象包括：
- 本地开发正常，CI 构建后某服务突然找不到类
- 两个微服务启动后，其中一个的
Helper::format()被另一个服务的同名函数替换 -
composer dump-autoload后 vendor/autoload.php 没变化——因为 Composer 只读当前项目的composer.json，不会扫描 symlink 进来的包
正确做法：用 path repository + 统一 autoload 配置
把共享包放在固定路径（如 ../shared-packages/my-utils），然后在每个主项目的 composer.json 中显式声明：
{
"repositories": [
{
"type": "path",
"url": "../shared-packages/my-utils"
}
],
"require": {
"myorg/my-utils": "*"
},
"autoload": {
"psr-4": {
"MyOrg\Utils\": "vendor/myorg/my-utils/src/"
}
}
}
关键点：
-
url必须是相对路径且所有环境都存在（不能写${HOME}/xxx或绝对路径） -
name字段在共享包的composer.json中必须和require里的完全一致（大小写、斜杠方向都不能错） -
autoload块写在主项目里，而不是共享包里——否则composer dump-autoload不会把它纳入主项目的自动加载逻辑 - 执行
composer update myorg/my-utils触发软链重建；如果软链消失，先检查共享包根目录下是否有composer.json和正确的name
改了共享包的 PSR-4 映射后，主项目不生效？
这是最常被忽略的一步：Composer 不会自动感知 symlink 包内部 composer.json 的变更。即使你更新了共享包的 "autoload": {"psr-4": {...}}，主项目仍沿用旧的映射。
必须手动在主项目中执行：
composer dump-autoload -o
原因：dump-autoload 会重新扫描所有已安装包（包括 path type 的 symlink 包）的 composer.json，并重写 vendor/composer/autoload_*.php。不加 -o 也能生效，但加了能强制刷新 classmap 缓存。
注意：
- 如果共享包新增了
"classmap": ["legacy/"]，主项目也得跟着加对应配置，否则那些文件不会被加载 - 团队协作时，确保 CI 流水线也执行这一步，否则新拉代码的人 vendor 里有包但类找不到
- 不要依赖
composer update自动触发 autoload 刷新——它只在依赖版本变更时才重生成 autoload，静态路径包内容变了不算“版本变更”
微服务场景下要不要 --optimize-autoloader
对长驻进程（Swoole、Octane、RoadRunner）来说，--optimize-autoloader 通常没用，甚至拖慢启动速度。因为：
- 类加载只发生在进程启动时一次，后续全走 OPcache
-
autoload_classmap.php是几 MB 的大数组，PHP 每次 require 都要完整解析，而单次请求只用到其中不到 5% 的类 - strace 可观察到大量
read()大文件操作，这不是 autoload 慢，是 classmap 文件体积过大拖累了 PHP 解析
真正该做的是：
- 启用
opcache.preload，把框架核心类（如IlluminateFoundationApplication）提前编译进内存 - 若必须用 classmap（比如 legacy 动态拼类名），改用
composer dump-autoload --classmap-authoritative --no-dev并精确指定目录（如"classmap": ["app/Models/"]），避免扫整个app/ - 确认
composer.json里没有冗余的"classmap"配置——没有就别强求-o
共享包的 autoload 性能问题，根源不在是否加 -o，而在于是否让每个服务都用同一套命名空间映射逻辑，且不互相污染。
