在 composer.json 顶层添加 repositories 指向 Fork 的 vcs 地址，并在 require 中使用完全一致的包名和存在的分支（如 dev-main），即可让 composer update 加载 Fork 版本；需确保 tag 已推送到远端，且无其他依赖强制降级。
怎么让 Composer 加载自己 Fork 的包而不是原版
直接改 composer.json 里的 repositories，告诉 Composer：“这个包我另有来源”。不改源码、不删缓存、不碰全局配置，改完 composer update 就生效。
常见错误是只改了 require 里的版本号，但没声明新仓库——Composer 还是去 Packagist 找原包，自然拉不到你的 Fork。
- 在
composer.json顶层加repositories数组，类型设为vcs -
url填你 Fork 的 GitHub/GitLab 地址（比如https://github.com/yourname/package-name） -
require中的包名必须和原包完全一致（包括 vendor 名），版本号写你 Fork 里存在的分支或 tag，比如"dev-main"或"dev-fix-login-bug"
示例片段：
{
"repositories": [
{
"type": "vcs",
"url": "https://github.com/yourname/laravel-debugbar"
}
],
"require": {
"barryvdh/laravel-debugbar": "dev-main"
}
}
为什么 dev-* 分支能用，但 v1.2.3 tag 拉不到
Composer 默认只识别远程仓库里已有的 tag 和分支。如果你 Fork 后没同步原 repo 的 tag，或者自己 push 了新 tag 但没带 -f 或没推到远端，Composer 就查不到。
使用场景：你想复刻一个包，修个 bug 后打个临时 tag 测试，但 composer update 报错 Could not find package xxx at version v1.2.3。
- 确认 tag 真的存在且已 push：
git tag看本地有没有，再git ls-remote --tags origin查远端 - 如果只是本地 tag，执行
git push origin v1.2.3（注意别漏掉v） - 若用分支开发，优先写
dev-fix-header-auth而不是猜 tag 名；分支名必须和远程一致，大小写敏感 - 某些私有 Git 服务（如 Gitee）对 tag 解析较弱，建议优先走分支
composer update 还是装了原包？检查这三处
最常踩的坑是“以为改了，其实没生效”，尤其当原包版本约束太宽（比如 ^3.0）时，Composer 可能绕过你的 Fork，选了个兼容的旧版原包。
- 运行
composer show vendor/package，看输出里的source是否指向你的 Fork 地址 - 检查
composer.lock里对应包的source字段，它才是最终依据；如果还是原地址，说明repositories没生效或版本不匹配 - 确认没有其他依赖间接 require 了同一包的其他版本（比如 A 依赖
package:^2.0，而你 requirepackage:dev-main），Composer 会按依赖树取交集，可能降级
上线前必须清理的隐藏风险
Fork 包适合调试和快速验证，但不能直接上生产——你的 Fork 缺少原作者的持续更新、安全修复和兼容性测试。
容易被忽略的是：你 Fork 的分支如果基于一个老 commit，后续原包发了 v4.1.0 修复了关键漏洞，你的代码不会自动获得该修复。
- 上线前把 Fork 改回稳定 tag，并提 PR 到上游；哪怕没被合，也能明确知道差异点
- 在
composer.json里加注释，标明 Fork 原因和预期替换时间，比如// TODO: 替换为 upstream v4.2.0 后移除 repositories - CI 流程中加一步检查：
composer show vendor/package | grep -q "yourname"，防止误提交 Fork 配置到主干
真正麻烦的不是怎么切过去，而是忘记什么时候该切回来。
