典型表现是执行composer require vendor/name报“could not find package”，或composer show --all不列出该包，主因是repositories未写在composer.json根级、url路径错误、本地包缺少name/version/autoload字段、大小写不匹配或未配置symlink选项。
composer.json里repositories配置不生效的典型表现
执行composer require vendor/name报Could not find package vendor/name，或者composer show --all里压根没列出该包——这几乎肯定不是网络或缓存问题，而是repositories配置未被识别。
常见原因包括：
-
repositories没写在项目根目录composer.json的**根级字段**，而是塞进了require、config或其他嵌套位置 -
url值写成了绝对路径（如/home/user/pkg）或带file://前缀，应改用相对路径（如"../my-pkg"），末尾不能加/ - 本地包目录下没有
composer.json，或该文件语法错误（比如尾逗号、单引号、中文引号）、缺name或version字段 -
name字段大小写、分隔符不一致：例如本地包写的是"acme/utils"，但require里写成"Acme/Utils"或"acme_utils"，就会静默失败
本地包composer.json必须包含哪些字段
Path仓库不是“把文件夹拖进来就行”，Composer会严格校验本地包自身的composer.json。它只认三个核心字段，缺一不可：
-
name：必须和require中写的字符串逐字一致（包括大小写、短横线-，禁用下划线_或大写字母） -
version：可写"dev-main"、"dev-develop"等，不能留空；若本地包是Git仓库，且当前分支叫main，就用dev-main -
autoload：至少声明psr-4或psr-0映射，否则类能装进vendor/，但new Class()会报Class not found
另外，若你希望强制启用符号链接（尤其在Windows或Docker中避免fallback到copy），需显式加上：
"options": {
"symlink": true
}
为什么改了本地代码，项目里没生效
看到vendor/vendor/name是个普通文件夹，而不是软链（Linux/macOS下ls -la显示->，Windows下dir显示JUNCTION），说明Composer fallback到了复制模式——你改的本地代码，根本没进vendor。
关键点不在主项目的配置，而在本地包自己的composer.json里是否含"options": {"symlink": true}。漏掉这句，即使：
- Windows下以管理员身份运行终端
- Docker容器加了
--cap-add=SYS_ADMIN - 主项目
config里设了"preferred-install": {"vendor/name": "source"}
都可能静默失败。验证方式永远是直接检查vendor/vendor/name是不是链接，而不是看有没有报错。
composer install vs composer update行为差异
composer install只重建缺失的链接，不会刷新已有链接的目标路径。也就是说，它完全依赖composer.lock里记录的解析结果——这个结果早在第一次composer require或composer update时就已固化。
所以，改完本地包代码后，必须运行：
-
composer update vendor/name（推荐）：只重算该包，快且安全 - 不要用
composer install，它什么也不做 - 避免无参数的
composer update，容易意外升级其他依赖
CI/CD环境要特别注意：path仓库在构建机上必然失效（路径不存在），上线前务必从repositories中移除对应条目，否则构建会卡死或失败。
