Composer不支持运行时动态解析包名，因依赖图构建在安装/更新阶段完成，require值必须是静态字符串，不执行PHP表达式或环境变量；租户模块需通过ClassLoader::addPsr4()运行时动态注册PSR-4命名空间实现加载。
Composer 本身不支持运行时动态解析包名，所谓“按租户加载不同扩展”不能靠
的
字段实现——写死变量、拼接字符串或环境判断都会在
阶段直接报错
。
为什么
composer
.json 里不能写租户变量？
Composer 的依赖图构建发生在安装/更新阶段，所有
值必须是静态字符串。它不执行 PHP 表达式，也不读取
或
。常见错误包括：
在
中写
→ 解析失败，提示
本地手动改
切换租户模块 → 上线后因分支差异导致
失败或加载错版本
误以为
能扫描新模块路径 → 实际只处理
块声明的路径，对运行时注册无效
用 ClassLoader::addPsr4() 动态注册命名空间
核心思路是绕过
，利用 Composer 自带的
在运行时绑定命名空间到物理路径。关键函数是
。
确保租户模块目录结构符合 PSR-4（如
对应命名空间
）
在租户上下文初始化时调用：
必须检查是否已注册：
，避免重复污染 autoload 缓存
注册时机很重要：Laravel 中推荐在服务提供者
或
回调中执行，而非每次请求都调；PHP-FPM 下每个 worker 进程都需独立执行该逻辑
租户模块发布与部署注意事项
租户私有模块不应进入主项目
，但也不能裸放源码。正确做法是：
将租户模块作为独立包发布到私有仓库（如 Satis、Private Packagist），版本号按租户+功能打标（如
）
主项目不
它们，仅保留统一入口命名空间约定（如全部以
开头）
部署时把模块包解压到固定路径（如
），并确保 Web 服务器有读取权限
模块内不得依赖主项目未声明的全局包；如有共用工具类，应抽离为根项目
的共享包
最容易被忽略的是 ClassLoader 生命周期问题：addPsr4() 注册只对当前 PHP 进程生效。容器重启、PHP-FPM worker 复用、甚至某些 Swoole 热重载场景下，旧进程不会自动感知新模块路径——这不是缓存没清，而是实例没重建。务必确认注册逻辑在每个请求生命周期早期稳定触发。
composer.jsonrequirecomposer installInvalid package namerequire$_ENV.envcomposer.json"vendor/{$tenant}/module"invalid package namecomposer.jsoncomposer installcomposer dump-autoloadautoloadrequireClassLoader$loader->addPsr4()modules/tenant-a/src/FeatureX/Handler.phpAppTenantModulesAFeatureX$loader->addPsr4('App\TenantModules\A\', base_path('modules/tenant-a/src/'))in_array('App\TenantModules\A\', array_keys($loader->getPrefixesPsr4()))boot()app()->booted()composer.jsontenant-a/feature-x:1.2.0requireAppTenantModules{TenantId}modules/tenant-a/require