本地修改依赖后，主项目却没有同步生效？这是一个非常常见的 Composer 依赖问题，很多 PHP 开发者在本地调试 SDK 或扩展包时都踩过坑。其实，问题的根源并不在 composer update 这个命令本身，而在于 Composer 默认的依赖解析机制会直接绕过你电脑上已经修改好的本地代码。
为什么 composer require 无法加载本地路径包
核心原因在于 Composer 的工作方式：执行 composer require 时，本质上只是向 composer.json 的 require 字段写入依赖声明，然后触发默认的远程依赖安装流程。它更像是一套优先识别 Packagist 官方仓库的机制，除非你在配置中明确告诉它“这个包来自本地路径”，否则它不会主动读取本地目录中是否存在同名项目代码。
composer require的主要作用是修改require字段，并启动远程依赖解析流程。- 想让本地目录参与 Composer 依赖解析，必须在
repositories配置块中新增一条type: "path"记录。 - 这条记录里的
url必须使用相对于当前项目composer.json的相对路径（例如../my-sdk），不能写绝对路径，也不能使用file://协议。 - 如果本地包连最基本的
composer.json文件都没有，比如只是一个普通脚本目录，Composer 通常会直接报错退出，而且错误信息往往不够直观。
type: "path" 配置写在哪、怎么写才有效
这项配置必须写在项目根目录 composer.json 的顶层 repositories 数组中。它的作用并不是“新增依赖”，而是“指定依赖来源”。也就是说，先声明一个本地仓库来源，再在 require 中声明你要引用这个来源里的具体包。
- 一个标准的配置示例：
{ "repositories": [ { "type": "path", "url": "../php-management-api-client" } ], "require": { "storyblok/php-management-api-client": "@dev" } } - 这里的
"@dev"非常关键。它告诉 Composer：这个依赖允许使用开发版本，也就是本地尚未打 tag 的代码。如果省略这一项，即使已经配置了path，Composer 仍然可能优先选择 Packagist 上的稳定版，从而忽略你的本地包。 - 如果项目中同时引用多个本地包，可以直接在
repositories数组中继续追加对象，每个对象对应一个独立的url路径。 - 配置完成后，建议删除
vendor/和composer.lock，然后重新执行一次composer install。旧的锁文件会持续锁定之前的远程依赖，不清理的话新的本地路径配置往往不会真正生效。
本地包改动后，主项目为何还是旧行为
这类问题最常见的原因通常不是缓存，而是自动加载没有刷新，或者实际修改的并不是正在被引用的代码位置。Composer 的 path 模式并不会复制文件，而是在 vendor/ 中创建一个符号链接（Linux/macOS）或 junction 连接点（Windows），直接指向你的本地目录。因此，只要路径配置正确、链接建立成功，本地源码一旦修改，效果通常应该立即体现出来。
- 先检查
vendor/storyblok/php-management-api-client这个目录，可通过ls -la查看它是否为软链接，以及目标路径是否准确指向你的本地项目目录。 - 如果看到的是普通文件夹而不是链接，说明上一次
install并没有正确建立本地路径依赖。较常见的原因是本地包的composer.json缺少name或version字段，导致 Composer 无法正常识别该包。 - 本地代码修改后，通常不需要额外执行
composer dump-autoload，因为符号链接已经存在，类文件路径本身没有变化。但如果你新增了类文件，并且项目使用的是 PSR-4 自动加载规则，那么就需要运行一次composer dump-autoload来刷新自动加载映射。 - 另外，PHP 的 OPcache 也可能继续缓存旧字节码。开发环境下建议关闭它：可以在
php.ini中设置opcache.enable=0，或者临时在代码里调用opcache_invalidate()清理缓存。
调试时误删 vendor/ 导致 composer install 失败怎么办
这种情况下最常见的报错是“Your requirements could not be resolved”。本质上是因为 Composer 在重新构建依赖关系时，发现本地 path 包的 composer.json 中声明了当前环境并不满足的 PHP 版本或扩展依赖，例如写了 "ext-gmp": "*"，但本机并未安装该扩展。
- 先检查本地包
composer.json中的require字段，确认是否声明了当前开发环境中未安装的扩展，例如"ext-redis": "*"但系统里没有启用 redis 扩展。 - 如果只是临时调试，可以执行
composer install --ignore-platform-reqs跳过平台依赖检查，但这只适合本地排查问题，绝不能作为正式方案提交到版本控制中。 - 更稳妥的处理方式是：尽量把本地包中的平台要求写得更宽松一些。例如将 PHP 版本限制写成
"php": ">=7.4"，而不是"php": "^8.2"，这样通常更有利于兼容不同开发环境。 - 如果执行
composer install时提示找不到repositories中配置的路径，那么大概率是url写错了。可以通过pwd和ls -la ../your-package实际检查目标路径是否真实存在。
还有一个特别容易忽视的细节：本地 path 包的 composer.json 中必须包含合法的 name 字段，格式必须是 vendor/name，并且要与主项目 require 中填写的包名完全一致，哪怕一个字符都不能出错。Composer 对名称匹配非常严格，大小写、中划线、下划线都可能影响识别结果，这一点在排查本地 Composer 路径依赖失效问题时一定要重点检查。
