composer如何添加本地路径包_composer path repository教程【开发】

composer 添加本地包报“package not found”是因为未在根 composer.json 的 repositories 中声明 path 类型仓库，或路径错误、类型未设为 path；path 模式下版本号被忽略，只认目录结构和 require 约束，且分支名须与本地 git 分支一致。

composer 添加本地包为什么总报 Package not found

因为 composer.json 里没配 repositories，或者路径写错、类型没设对。Composer 默认只查 packagist.org，本地路径必须显式声明为 path 类型仓库，且路径必须是相对于 composer.json 文件所在目录的绝对或相对路径（推荐用相对路径）。

常见错误现象：Could not find a matching version of package vendor/name，哪怕本地包的 composer.json 里写了 "version": "dev-main" 也无效——版本号在 path 模式下被忽略，它只认目录结构和 require 中的约束。

• 确保本地包根目录下有合法的 composer.json，含 name 和 autoload
• 项目根目录的 composer.json 中添加：

  "repositories": [   {     "type": "path",     "url": "./packages/my-local-package"   } ]

• url 值不能以 ../ 开头（部分 Composer 版本会拒绝解析），建议把本地包放在项目内子目录
• 运行 composer require vendor/name:dev-main，不是 dev-master 或 1.x-dev —— path 模式下分支名必须跟本地 Git 分支一致，且不校验 version 字段

path repository 的 options.symlink 是干啥的

它控制 Composer 安装时是否用符号链接代替复制文件。开启后，vendor/vendor/name 实际指向你本地包目录，改代码立刻生效，适合边开发边调试；关掉就是普通拷贝，更稳定但每次 composer update 都会覆盖。

使用场景：你在写一个 SDK，同时在多个项目里试用，需要实时看到修改效果。

• 启用方式：在 repositories 条目里加 "options": { "symlink": true }
• windows 用户注意：symlink 需管理员权限 + 启用开发者模式，否则报错 failed to create symbolic link
• CI 环境通常禁用此选项，避免因权限或文件系统限制导致构建失败
• 一旦启用，composer install 会跳过该包的下载/解压步骤，直接建链接

为什么 composer update 不拉取本地包的最新代码

因为 path repository 默认不追踪 Git 变更，它只读取本地目录当前文件状态。你改了本地包的源码，只要没删 vendor 重装，Composer 就认为“已安装最新”——它根本不管 Git commit 或分支有没有动。

这跟 packagist 上的包逻辑完全不同：后者靠版本号触发更新，前者靠文件系统快照。

• 想强制刷新：删掉 vendor/vendor/name 目录，再跑 composer install
• 不想删目录？用 composer dump-autoload 更新自动加载映射（仅当改了 autoload 规则时必要）
• 如果本地包用了 Git，又希望自动同步，得自己加脚本监听变更，Composer 本身不提供这个能力
• 多人协作时，别把 symlink: true 提交到公共配置里，容易导致别人环境出错

本地包依赖另一个本地包，怎么链起来

不能只在主项目里配一个 repositories，每个被依赖的本地包，都得单独声明。Composer 不递归解析依赖包里的 repositories，所有路径仓库必须集中注册在最外层 composer.json 中。

比如 package-a 依赖 package-b，而两者都是本地路径，就必须这样写：

"repositories": [   {     "type": "path",     "url": "./packages/package-a"   },   {     "type": "path",     "url": "./packages/package-b"   } ]

• 顺序无关，但两个 url 路径必须真实存在且可读
• 如果 package-a 的 composer.json 里写了 "package-b": "dev-main"，那主项目 require package-a 时，Composer 才能连带装上 package-b
• 别指望用 path 仓库模拟私有 Packagist——它不支持版本别名、dist 包、元数据缓存等特性

路径仓库不是万能的替代方案，它绕过了版本约束检查，也绕过了网络隔离和权限控制。真要长期维护多个本地组件，值得花半天搭个轻量私有仓库（如 Satis 或 Toran Proxy），而不是靠一堆 path 配置硬扛。