Composer私有仓库版本号规范与更新同步机制-composer-PHP中文网

私有包更新后 composer update 拉不到新版本，大概率是 version 字段写法错误或 satis 构建配置未对齐：必须用规范 tag（如 "1.2.3"）而非 dev-main，且 satis 需显式配置 require 或 require-all 并手动 build，同时确保 repositories 正确声明、无 canonical 截断、composer.lock 未锁定旧版本。

composer私有仓库版本号规范与更新同步机制

私有包更新后 composer update 拉不到新版本？不是缓存问题，大概率是 version 字段写法或 Satis 构建配置没对上。

私有包的 `version` 字段怎么写才被 Satis 收录

Composer 本身不读取 Git 分支名来判断版本，它只认 composer.json 里的 version 字段。Satis（或其他私有仓库服务）扫描时，会提取这个字段生成 packages.json 元数据。

写死为 "version": "dev-main"：Satis 默认不收录 dev- 前缀的版本，除非你显式配置 "require-dependencies": true 或在 Satis 配置中用 "require": {"vendor/package": "dev-main"}
打 tag 后写成 "version": "1.2.3"：这是最稳妥的方式，Satis 在 "require-all": true 模式下会自动收录所有已打 tag 的稳定版本
混用 "dev-main || ^2.0"：仅适用于 Satis 配置里明确声明该分支且 Git 仓库中存在对应 commit，否则解析失败，packages.json 里根本不会出现这个包

`composer update` 跳过私有包的常见触发条件

不是 Composer 不想拉，而是它压根没“看到”新版本——元数据没刷新、锁文件卡死、或者搜索顺序被 canonical 截断了。

First Principles Decomposer

把任何问题拆解为根本真理，再从原子层面重建解决方案。

下载

composer.lock 锁定了旧版本，执行 composer update vendor/package 时没加 --with-dependencies，导致依赖链上游没更新，下游包被跳过
项目 composer.json 的 repositories 里漏配或拼错，比如写成 "type": "git" 而非 "vcs"，Composer 直接忽略该源
私有源排在 Packagist 后面，而 canonical 机制生效（Composer 2.x 默认），Packagist 先命中同名包就终止搜索，你的私有 v2.1 根本没机会被考虑
本地缓存的 packages.json 还是旧的，composer clear-cache 不清它，得用 composer update --refresh（≥2.5）或手动删 ~/.composer/cache/repo/https---packages-example-org/

Satis 构建时如何确认新 tag / branch 真被扫进去了

Satis 不监听 Git 变更，必须手动 build，且 build 日志才是唯一可信依据。别信“我 push 了，应该有了”这种直觉。

构建命令末尾加 -v 参数：satis build satis.json web/ -v，终端会逐行打印它解析了哪些 commit、tag 和 composer.json 内容
检查输出里是否有类似 Adding package vendor/package (dev-main) 或 Adding package vendor/package (1.2.3) 的日志行；没有就说明没扫到
访问生成的 packages.json 文件（如 https://packages.example.org/packages.json），搜索你的包名，确认 versions 数组里包含预期版本
若想同时收 dev-main 和 v1.2.3，Satis 配置不能只靠 "require-all": true，得写成："require": {"vendor/package": "dev-main || ^1.2"}

客户端验证是否真从私有源加载包

别只看 composer show vendor/package 输出的版本号，关键要看来源地址——它决定了 Composer 到底连的是哪台服务器。

运行 composer show -p vendor/package，重点看 source 行：应显示你的私有域名（如 https://packages.example.org），而不是 https://api.github.com/ 或镜像站地址
临时绕过缓存验证：加 --no-cache -v，观察终端请求 URL 是否命中私有源，比如出现 GET https://packages.example.org/p2/vendor/package/1.2.3.json
检查当前生效镜像：全局配置用 composer config -g repo.packagist，项目级则用 composer config repo.packagist，避免项目 repositories 覆盖了私有源设置