中文包的version字段必须留空，否则tag解析失效；正确做法是删除version字段，依靠Git Tag驱动版本识别，并确保CI校验tag存在、私有源同步监听push --tags事件。
中文包的 version 字段必须留空，否则 tag 解析失效
企业内部发布的中文 SDK（如 acme/wechat-sdk）若在 composer.json 中硬写 "version": "1.2.0"，Composer 就不会读取 Git Tag，导致 composer install 拿到的是 commit hash 而非语义化版本，composer outdated 也无法比对真实发布状态。
- 正确做法：删掉
version字段，靠 Git Tag 驱动版本识别 ——v1.2.0必须存在且带注释（git tag -a v1.2.0 -m "release: wechat sdk v1.2.0"） - CI 构建前需校验：
git describe --tags --exact-match HEAD，失败即中止，防止无 tag 提交被误发 - 私有源（如 Satis）同步脚本必须监听
git push --tags事件，而非轮询分支；否则新 tag 永远不会进 packages.json
path 仓库不是开发捷径，而是隔离起点
把 repositories.type=path 当成“改完立刻生效”的调试手段，等于绕过整个生命周期管控：autoload 不校验、版本不解析、CI 中无法还原。它唯一合法用途，是本地验证已注册到私有源的正式包。
-
composer.json中的name必须与私有源注册名完全一致（含 vendor），例如"acme/wechat-sdk"，不能简写为"wechat-sdk" - 执行
composer update acme/wechat-sdk，而非install—— 后者不触发 path 映射加载 - CI 流水线必须清除所有
repositories配置，或设COMPOSER_DISALLOW_UNSAFE_AUTH=1，否则 path 会静默污染构建结果
post-autoload-dump 是中文包初始化的唯一可靠入口
中文 SDK 常需加载词典、初始化连接池、注册全局事件钩子——这些动作依赖 autoloader 已就绪。用 post-install-cmd 或 post-package-install 都不可靠：前者不保证 autoload 生成，后者只对直连依赖生效。
- 在包的
composer.json中声明："scripts": {"post-autoload-dump": "php -f vendor/acme/wechat-sdk/bin/init.php"} -
init.php内应包含require_once __DIR__.'/../vendor/autoload.php';，确保类加载器可用 - 避免在脚本里调用
composer dump-autoload—— 这会触发递归，导致死循环或 autoload 失效
abandoned 状态无法被 composer audit 自动识别
composer audit --abandoned 只查 Packagist 元数据，对走私有源（repositories.type=composer）的中文包完全无效。即使你在自己包里写了 "abandoned": "acme/new-wechat-sdk"，安装时也不会提示。
立即学习“PHP免费学习笔记（深入）”；
- 实际可行方案：在 CI 中运行
find vendor -name composer.json -exec grep -l '"abandoned":' {} \;，发现即失败 - 私有源（如 Satis）需手动在
packages.json对应包条目下添加"abandoned": true字段，Satis 支持该字段透出 - 根项目
composer.json的config.audit.ignore-abandoned应留空，否则会跳过所有废弃检查
composer.json 的耦合关系、path 仓库的误用边界、以及 post-autoload-dump 这种非显性但强依赖的时机控制 —— 它们都不报错，但会让版本可追溯性在上线前最后一刻崩塌。 
