path repository 是 Composer 的本地仓库类型，用于将本地文件夹作为包源加载，适合开发中依赖、未发布内部组件或第三方补丁验证；需在 composer.json 中配置 repositories 字段并确保路径、name 和 autoload 正确。
什么是 path repository，它适合什么场景
Composer 的 path repository 是一种本地仓库类型，允许你把本地文件夹当作一个包源来加载，不走 Packagist 或私有 Satis/Satis 服务。它最常用于：正在开发中的依赖包、尚未发布到 Packagist 的内部组件、或需要快速验证修改效果的第三方包补丁。
注意：path repository 不会自动监听文件变化，也不会触发自动重安装；它只是让 Composer 知道“这个路径下有个符合 PSR-4 + composer.json 规范的包”，后续仍需手动 composer update 或 composer require。
如何在项目中配置 path repository
在项目的 composer.json 根目录中添加 repositories 字段（不是包自己的）：
{
"repositories": [
{
"type": "path",
"url": "../my-local-package"
}
],
"require": {
"vendor/my-local-package": "*"
}
}
关键点：
-
url必须是相对于当前composer.json文件的路径，支持../、./packages/xxx，但不支持绝对路径（如/home/user/pkg）或环境变量 - 目标文件夹必须包含合法的
composer.json，且其中name字段（如"vendor/my-local-package"）要和require中的一致 -
"*"版本约束会被解析为该目录下composer.json中的version值；若没写version，默认用dev-main（或dev-master），此时需确保require写成"vendor/my-local-package": "dev-main"
path repository 的符号链接行为与陷阱
Composer 在安装时会对 path 类型包创建符号链接（symlink），而不是复制文件——这是它高效调试的核心机制，但也带来几个典型问题：
GInstall OneClick — 一键安装 GitHub 项目：规划、克隆、安装 Node 依赖、运行开发脚本。适用于想要获取 GitHubNode.js 项目的用户。
常见错误现象：修改本地包代码后，运行报错说“类找不到”或“方法不存在”，但 composer dump-autoload 也没用。
原因通常是：
- 目标包的
autoload配置未覆盖实际文件路径（比如 PSR-4 的命名空间前缀和目录映射写反了） - 项目主
autoload没有重新生成（执行composer dump-autoload只影响当前项目，不会自动 reload symlink 包的 autoloader） - 某些 IDE 或 PHP 扩展（如 opcache）缓存了旧的类路径，需清理 opcache 或重启 PHP-FPM / CLI 进程
- Windows 下启用 symlink 需管理员权限运行终端，否则 Composer 会 fallback 成硬拷贝，导致后续修改不生效
如何安全地切换回正常包源（比如 Packagist）
当本地调试完成，想切回稳定版本时，不能只删 repositories，还要注意两件事：
- 先执行
composer remove vendor/my-local-package，再删repositories和require条目，否则 Composer 可能继续从本地路径加载 - 检查
vendor/composer/installed.json，确认对应包的source类型已变为dist或git，而非path - 如果之前用了
dev-main，而 Packagist 上最新稳定版是1.2.0，记得把require改成"vendor/my-local-package": "^1.2"，否则 Composer 仍可能锁定dev-main
路径仓库看似简单，但 symlinking、autoloading、版本解析三者叠加后，很容易出现“改了代码却没生效”的静默问题——每次怀疑失效时，优先检查 vendor/vendor-name/package-name 是否真是个软链，以及 composer show vendor/my-local-package 输出里的 source 字段值。
