在 composer.json 中声明 fork 包需在 repositories 字段添加 type 为 vcs 的仓库地址，且 fork 仓库的 name 必须与原包一致；通过 dev-前缀指定分支（如 "dev-main"）或 commit（如 "dev-main#abc1234"），并配置 prefer-source: true 和 minimum-stability: dev 避免拉取失败。
怎么在 composer.json 中声明 fork 的包
Composer 本身不区分“官方包”和“fork 包”，它只认 name 和 source。关键在于把 fork 后的仓库地址告诉 Composer，并确保 name 与原包一致（否则会冲突）。
必须在 composer.json 的 repositories 字段中显式添加你的 fork 地址，类型设为 vcs：
"repositories": [
{
"type": "vcs",
"url": "https://github.com/yourname/package-name"
}
]
然后照常运行 composer require vendor/package-name 或修改 require 版本 —— Composer 会优先从你声明的 repositories 中匹配，而不是 Packagist。
注意：url 必须是可被 Composer clone 的 Git 地址（支持 HTTPS/SSH），且该仓库的 composer.json 中 name 字段需与你要替换的包完全一致（例如 "laravel/framework"），否则无法覆盖。
如何指定 fork 分支或 commit 而不是稳定版本
默认情况下，Composer 拉取的是 dist（即 Packagist 缓存的 zip 包），但 fork 仓库通常没发布过 tag，所以得强制走 source（即 git clone）并指定开发分支。
- 在
require中用dev-前缀：例如"vendor/package-name": "dev-main"或"dev-fix-redis-timeout" - 加
"prefer-source": true到根composer.json，避免因缺少 dist 包而失败 - 如果只想固定某个 commit，可用
"dev-main#abc1234"（注意#后是 commit hash，不是 tag）
不推荐直接写 "*" 或 "dev-master"（已废弃），容易因分支重命名或更新不可控导致构建漂移。
为什么 composer update 没拉到 fork 的最新代码
常见原因不是配置错，而是 Composer 缓存了旧的元数据或已安装的 dist 包。
- 先删掉
vendor/vendor/package-name目录，再运行composer update vendor/package-name - 执行
composer clear-cache，尤其当你改过repositories后又换过分支名 - 检查是否误启用了
packagist.org镜像（如阿里云镜像），某些镜像会忽略自定义repositories；可在composer config -g repo.packagist查看，必要时禁用：composer config -g repo.packagist false
还有一个隐藏坑：如果你 fork 的仓库没有设置 minimum-stability 或 prefer-stable: true，而原包要求 stable 版本，那 dev- 分支会被跳过 —— 此时需在根 composer.json 显式加 "minimum-stability": "dev" 或为该包单独设 "stability-flags"。
长期维护 fork 包时怎么避免每次手动同步上游
fork 不是终点，上游更新后你得合并，否则很快脱节。纯靠人工 cherry-pick 效率低、易漏。
- 在 fork 仓库里添加上游 remote：
git remote add upstream https://github.com/original-vendor/package-name.git - 定期 fetch：
git fetch upstream，然后git merge upstream/main（或 rebase） - 建议在 fork 仓库的
README.md里写明当前基于 upstream 的哪个 commit，方便回溯 - 如果修改点少，考虑用 patch 文件 +
cweagans/composer-patches插件替代 fork，更轻量、更易升级
真正麻烦的不是第一次引入 fork，而是三个月后谁还记得那个 dev-hotfix-202404 分支到底合没合 upstream 的安全补丁。
