Composer 依赖解析失败的根源在于拆库后 path 仓库失效、版本号未交由 Git tag 驱动、autoload 命名空间未按包独立配置及私有仓库认证未正确透传，需同步修正这四点。
Composer 依赖解析失败：monorepo 中的 path 仓库在拆分后不生效
拆库后最常见现象是 composer install 报错：Could not find package vendor/package-name，或提示找不到本地 path 类型仓库。这是因为 Composer 默认只从 packagist.org 或配置的 repositories 拉取，而你原来 monorepo 的 "type": "path" 配置（比如指向 ../packages/foo）在新仓库里路径已失效。
必须显式声明每个子包的独立源：
- 在每个子包的
composer.json中保留"name"（如"acme/utils"），且不能和 monorepo 时代用的虚拟名冲突 - 主项目（如 Laravel 应用）的
composer.json需添加对应repositories，例如："repositories": [ { "type": "vcs", "url": "https://github.com/acme/utils" } ] - 避免混用
path和vcs：开发阶段想临时链接本地包？用composer config repositories.local path ../utils，但上线前务必删掉——否则 CI 会因路径不存在失败
版本号管理断裂：monorepo 的统一发版节奏如何延续
Monorepo 常靠 Lerna 或 custom scripts 实现“所有包一起 bump 版本”，但 Composer 本身不支持跨包版本联动。直接照搬会导致子包 version 字段写死（如 "version": "1.2.0"），下次改一个包就得手动改所有相关依赖的 require。
正确做法是放弃在 composer.json 里写死 version，完全交由 Git tag 驱动：
- 每个子包发布时打语义化 tag（
v1.2.0），Composer 会自动识别为版本 - 主项目中用
"acme/utils": "^1.2"这类约束，而非"dev-main"—— 后者在私有包场景下极易因分支重命名或 force push 失效 - CI 流水线里加一步：检测
git describe --tags --exact-match是否成功，失败则拒绝发布，防止 tag 漏打
autoload 冲突：monorepo 的 PSR-4 根目录映射在拆分后报 Class not found
原 monorepo 可能用一个大 "autoload": {"psr-4": {"Acme": "src/"}} 覆盖所有子模块，拆库后若没调整，Composer 会按旧路径去加载，结果当然是 Class 'AcmeUtilsHelper' not found。
每个子包必须独立定义 autoload，并确保命名空间与 name 一致：
- 包
acme/utils的composer.json必须写："autoload": { "psr-4": {"Acme\Utils\": "src/"} } - 不要复用 monorepo 的顶层命名空间（如
"Acme\"），否则多个包会互相覆盖自动加载规则 - 运行
composer dump-autoload -o后检查vendor/composer/autoload_psr4.php，确认你的命名空间映射是否出现在其中——这是验证 autoload 是否生效的最快方式
私有包认证失败：GitHub/GitLab 私有仓库 401 错误
当子包托管在私有 Git 仓库时，composer install 常卡在 Cloning into '/path/to/vendor/acme/utils'... 并报 401 Authentication failed。这不是 Composer 配置问题，而是 Git 凭据未透传。
关键点在于：Composer 调用的是系统 Git，不是你的 SSH Agent 或 GitHub CLI 登录态：
- 用 HTTPS 方式时，在
auth.json里配 token：{ "github-oauth": { "github.com": "ghp_xxx..." } } - 用 SSH 方式时，确保
git@github.com:acme/utils.git能被当前用户git clone成功；Composer 不读~/.ssh/config别名，所以 URL 必须是标准格式 - CI 环境（如 GitHub Actions）别硬编码 token，用
${{ secrets.GITHUB_TOKEN }}注入到auth.json，且记得chmod 600 auth.json，否则 Composer 会跳过加载
拆库后最麻烦的从来不是配置，而是所有子包的版本约束、autoload 命名空间、Git 认证这三件事必须同步对齐——漏一个，composer install 就会在不同环节静默失败。
