Composer如何在本地测试即将发布的包版本？（inline-alias技巧）

直接在项目中验证本地包修改的最有效方法是结合使用 path 类型仓库与 inline-alias：先在 composer.json 的 repositories 中配置本地路径，再通过 composer require vendor/name:dev-branch as x.y.z 强制指定版本别名，确保所有依赖（包括间接依赖）均指向本地代码，并需清理 composer.lock 以生效。

用 composer require 直接安装本地包的开发分支

你改完包代码，想立刻在项目里验证效果，又不想发版、推远程、等 Packagist 同步——最直接的办法是把本地路径当仓库用。composer require 支持用 path 类型仓库，但要注意：必须在项目根目录的 composer.json 里先声明仓库，否则会报 Could not find package xxx at any version。

实操建议：

• 在项目 composer.json 的 repositories 数组里加一条：

  {"type": "path", "url": "../my-package"}

  （路径相对于项目根目录）

• 运行 composer require vendor/my-package:dev-main（分支名要和你本地仓库一致）
• 如果包的 composer.json 里没设 "minimum-stability": "dev"，还得在项目里显式加 "minimum-stability": "dev"，否则 dev-main 不被接受
• 装完后检查 vendor/vendor/my-package 是个 symlink，指向你本地目录——这是关键信号，说明生效了

用 inline-alias 强制覆盖已安装包的版本约束

你已经在项目里装了 vendor/my-package:^2.1，现在本地改了 dev-fix-login-bug 分支，想临时切过去测试，但又不想删掉已装包重来——这时候 inline-alias 就是唯一不破坏依赖图的解法。

常见错误现象：直接 composer require vendor/my-package:dev-fix-login-bug 报错 your requirements could not be resolved，因为 Composer 认为 dev-fix-login-bug 不满足 ^2.1 的约束。

实操建议：

• 用 composer require vendor/my-package:dev-fix-login-bug as 2.1.99，其中 2.1.99 必须落在原约束范围内（^2.1 允许 2.1.0 到 2.999.999）
• 别写成 2.2.0——虽然数字更大，但 ^2.1 默认不接受 2.2.x，除非你改约束
• 这个 alias 只影响当前 require 动作，不会改包自身的 version 字段，所以 composer show vendor/my-package 显示的还是 dev-fix-login-bug

为什么 path 仓库 + inline-alias 要一起用？

单独用 path 仓库能装本地代码，但一旦包被其他依赖间接引入（比如 another-package 依赖了你的包），Composer 就可能忽略你的 path 配置，回退到 Packagist 上的版本——这是最隐蔽的坑。

原因在于：Composer 解析依赖时，优先按包名+版本号匹配，而 path 仓库只对显式 require 生效；间接依赖走的是 lock 文件记录的源，不是实时仓库配置。

实操建议：

• 只要涉及多层依赖，就必须给本地包加 inline-alias，确保所有路径都强制走你指定的本地版本
• 运行 composer update vendor/my-package --with-dependencies，让 Composer 重新计算整个子图，并把 alias 应用到所有相关节点
• 检查 composer.lock 里对应包的 source 字段是否变成 "type": "path" 和正确路径——这是唯一可信的验证方式

composer install 时本地路径失效的典型场景

CI 环境或新同事拉代码后运行 composer install，报错 Source path ../my-package does not exist，但你在本地明明能跑通——这不是配置问题，是路径假设错了。

根本原因是：path 类型仓库的 URL 是相对路径，它从执行 composer install 的目录算起。如果你在 CI 里进了子目录再执行，或者用 docker 挂载时路径映射不一致，就会断。

实操建议：

• CI 中统一用绝对路径（如 /home/app/my-package），并确保容器内该路径真实存在且可读
• 开发机上避免嵌套执行 composer 命令，始终在项目根目录操作
• 临时方案：用 composer config repositories.local '{"type":"package","package":{"name":"vendor/my-package","version":"dev-main","dist":{"url":"/absolute/path/to/my-package.zip","type":"zip"}}}' 绕过路径依赖（需提前打包）

实际测试时最容易漏掉的是锁文件残留——哪怕你改了 composer.json 并 require 新 alias，composer.lock 里旧的源信息可能还在，导致下次 install 依然拉远端包。删 lock 文件重装不是懒，是必要步骤。