Composer 的 version 字段应留空或与 Git 标签严格一致，因依赖解析实际依赖 tag（如 v1.2.3），而非该字段；硬写错误版本会导致 Packagist 拒绝或校验失败，且语义化版本匹配取决于合规的 tag 和无破坏性变更。
Composer 的 version 字段到底该填什么
直接填 "version": "1.2.3" 是错的——Composer 不读这个字段做依赖解析，它只在你用 composer install 本地安装时、或发布到 Packagist 时参考一次。真正起作用的是 Git 标签（tag），比如 v1.2.3 或 1.2.3。
如果你在 composer.json 里硬写 "version": "dev-main"，又没打对应 tag，Packagist 会拒绝收录；如果写了 "version": "1.2.3" 却打了 v1.2.4 标签，Composer 安装时会以 tag 为准，但 Packagist 可能报校验失败。
- 发布前必须用 Git 打 tag：
git tag v1.2.3（推荐带v前缀，兼容性更好） - 确保
composer.json中的"version"字段与 tag 一致，或干脆删掉——让 Packagist 自动从 tag 推断 - 别用
dev-前缀伪造稳定版，比如"version": "dev-1.2.3"，这会让 Composer 认为它是开发分支，不满足^1.2这类约束
如何让 composer require 正确匹配语义化版本约束
关键不在你“怎么写”，而在别人“怎么 require”。你的包能否被 ^1.2、~1.2.0 正确命中，取决于你发布的 tag 是否符合 SemVer 规则，且没有破坏性变更混进补丁版。
常见错误是：把 BC-breaking 更改塞进 v1.2.4，结果下游项目执行 composer update 直接崩掉——因为 ^1.2 允许升级到 1.9.9，但不保证兼容性。
- 小版本（
1.x）升级必须兼容：新增方法、可选参数、非强制返回值扩展都 OK；删方法、改方法签名、改返回类型属于大版本事 - 补丁号（
1.2.x）只允许修复 bug，不能加功能，更不能动接口 - 如果用了
dev-master作为依赖，它永远不响应^或~约束，只会锁定当前 commit —— 别在生产环境这么写
私有包打 tag 后 Composer 找不到新版本
不是 Composer 没刷新，而是它默认只信任已知源。如果你用的是私有仓库（如 Satis、Private Packagist 或自建 Toran），必须手动触发同步，或配置 composer.json 的 repositories 指向正确的 VCS 地址。
典型表现：composer show vendor/package 显示还是 v1.2.2，但 git ls-remote origin --tags 已能看到 v1.2.3。
- 确认
repositories类型是vcs，且 URL 是 Git 地址（不是 HTTPS 页面地址） - 运行
composer clear-cache，再composer update vendor/package（不要只require） - 私有包若未配置
dist信息，Composer 会走source方式克隆，此时必须确保服务器允许 Git 协议访问
为什么 composer update 不升到最新 patch 版本
不是锁文件（composer.lock）太旧，而是 composer.json 里写的约束太窄。比如写成 "vendor/package": "1.2.2"（精确版本），或 "1.2.*"（只匹配 1.2.x，但不包含 1.2.10 这种两位数补丁）。
1.2.* 实际等价于 >=1.2.0 ，但部分旧版 Composer 对 * 解析有偏差；而 ^1.2 才是现代推荐写法，它表示 >=1.2.0 。
- 用
^1.2.3表示“兼容 1.2.3 的所有后续补丁和小版本”，这是最安全的生产写法 - 避免
1.2.x这种写法——Composer 不识别x，会当作字面量匹配失败 - 执行
composer update vendor/package --with-dependencies才能连带更新其子依赖，否则可能因子依赖版本冲突卡住
语义化版本不是格式游戏，是契约。一个 v1.2.3 tag 被打出去，就代表你承诺所有 ^1.2 的用户不会因升级它而改代码。这点一旦破例，lock 文件就不再是保障，而是债务清单。
