私有仓库未配置时composer require会报“找不到包”；本地path仓库仅限开发，ci/cd需改用satis等私有源；name须全局唯一、type为"library"、autoload命名空间须与name严格对齐。

私有仓库没配对，composer require 会直接报错找不到包

本地 path 仓库只适用于开发阶段，一上 CI 或部署就失效——因为 vendor/ 是从远程拉的，不是软链接。必须提前把每个微服务模块打包成独立 Composer 包，并托管到私有仓库（如 Satis、Private Packagist 或自建 Git + Packagist 兼容接口）。关键点是：composer.json 中的 name 必须全局唯一（如 "myorg/user-service"），且不能和主项目或其他包重名；type 必须设为 "library"，否则 Packagist 不认；autoload.psr-4 的命名空间要与 name 对齐（比如 "MyOrg\UserService\": "src/"），末尾不加斜杠。

repositories 配置写错，包永远装不上

主项目或网关项目的 composer.json 里，repositories 必须显式声明私有源，且顺序影响解析优先级：

First Principles Decomposer

把任何问题拆解为根本真理，再从原子层面重建解决方案。

下载

• Git 类型：用 {"type": "vcs", "url": "https://git.example.com/myorg/user-service"}，Composer 会自动识别 tag 和分支
• Package 类型（适合 Satis）：用 {"type": "package", "package": {...}} 手动写死版本和 dist URL，但维护成本高
• 不要混用 packagist.org 和私有源而没设 "packagist.org": false，否则 Composer 仍会去公网查一遍，超时或命中缓存导致装错旧版

依赖版本锁不住，上线后行为突变

微服务之间调用公共契约包（如 myorg/contracts）时，若各服务 require 的版本范围太宽（如 "^1.0"），CI 构建时可能拉到不兼容的新版。正确做法是：

• 所有跨服务共享包（DTO、接口、基础 client）必须打语义化版本，并在 composer.json 中用精确版本锁定，例如 "myorg/contracts": "2.3.1"
• 主项目 composer.lock 必须提交进 Git，且部署时强制执行 composer install --no-dev -o，跳过 composer.json 解析过程
• 避免在包内 require 框架全量组件（如 laravel/framework），只留最小运行时依赖（如 psr/http-message、php-di/php-di）

autoload 冲突导致类加载失败

多个微服务包共用同一命名空间前缀（如都用 App\）或 autoload 映射路径重叠，composer dump-autoload -o 会覆盖彼此，最终只有最后一个生效。真实踩坑点包括：

• 子包的 autoload.psr-4 绝不能写 "App\": "src/" —— 这会污染主项目和其他包的自动加载规则
• 所有包必须使用专属命名空间，且与 name 严格对应（"myorg/auth" → "MyOrg\Auth\"）
• 主项目若保留单体结构，其 autoload 应收缩为仅覆盖自身入口逻辑，业务代码全部移出，交由微服务包提供

实际跑通的关键不在“怎么发包”，而在于每个包的 composer.json 是否干净、独立、无隐式上下文依赖。一旦某个包偷偷 require 了 Laravel 的 Facade 或框架特定配置加载器，它就不再是可复用的 library，而是绑死在某个单体环境里的“伪微服务”。