composer install 报“package not found”是因未配置 path 类型仓库，需在根 composer.json 的 repositories 中添加 "type": "path" 指向 packages/*，子包 name 要规范，require 用 "@dev"，禁用 packagist fallback，并注意 ci 和 ide 的路径识别问题。
composer install 时提示 “Package not found” 但本地有源码
monorepo 里把多个包放在同一仓库，但 composer.json 还按传统方式写，就会找不到本地路径下的包。Composer 默认只认 Packagist 或配置的远程仓库，不自动扫描子目录。
必须显式告诉 Composer：这些包就在当前仓库里，且用 path 方式加载：
- 在根目录
composer.json的repositories字段加一个 typepath的仓库，指向子包目录，比如"packages/*" - 子包自己的
composer.json中name必须规范（如myorg/utils），不能是localhost/utils这类非法名 - 根项目
require子包时，版本号得写"dev-main"或"*@dev"，不能写"1.0.0"—— 否则 Composer 会跳过 path 源去远程找
示例片段：
{
"repositories": [
{
"type": "path",
"url": "packages/*"
}
],
"require": {
"myorg/utils": "@dev"
}
}
子包 require 根项目的其他子包时循环依赖报错
比如 packages/api require packages/db，而 packages/db 又 require packages/core，一旦某处写错 require 关系或版本约束太死，Composer 会卡在依赖解析阶段，报 Root composer.json requires ... which is not installable。
根本原因是 path 类型仓库不参与版本“发布”，所有包都视为 dev-main，但 Composer 仍严格校验 require 版本是否满足。解决要点：
- 所有子包的
require都用"*"或"@dev"，避免写"^1.0"这类需要 tag 支持的约束 - 禁用 packagist.org 的 fallback：在根
composer.json加"packagist.org": false到repositories，防止 Composer 去远程瞎猜 - 运行
composer update --with-all-dependencies而非install，强制重解整个图
CI 环境下 vendor 安装慢或失败
本地跑得通，CI 上 composer install 却超时或报 Could not fetch，常见于用了 path 仓库但 CI 没拉全子目录、或缓存机制干扰。
关键不是网络，而是路径可见性：
- 确保 CI 构建前已 checkout 所有子包目录（Git 默认不会 sparse checkout，需显式配置）
- 不要在 CI 中用
--no-cache—— Composer 的 cache 会存 path 包的 hash，禁用后每次重算，反而更慢 - 如果子包有
autoload-dev或测试专用依赖，用composer install --no-dev减少解析量；但注意：若某个子包的autoload依赖另一个子包的 dev autoload，就真得带上--dev
PHPStorm 提示 “Class not found” 尽管运行正常
IDE 不理解 path 仓库映射，只按 vendor 目录索引，导致跳转失效、补全缺失、类型推导错误。
这不是 Composer 问题，是 IDE 配置缺失：
- 在 PHPStorm 中打开
Settings > PHP > Include Paths，手动添加每个packages/xxx目录 - 或者统一在根目录加一个
.phpstorm.meta.php，用override显式声明命名空间到路径映射 - 别依赖
vendor/autoload.php自动发现 —— 它只管运行时，不管 IDE 静态分析
最省事的做法：把所有 packages/* 目录设为 “Sources Root”（右键 → Mark as → Sources Root）。
monorepo 的麻烦不在 Composer 本身，而在工具链对 “本地路径即包” 这一前提的默认支持不足。每加一个新工具（psalm、phpstan、CI runner），都要单独确认它是否识别了你的 path 映射逻辑。
