本地代码发布必须完成“规范配置→打tag→Packagist提交→验证安装”四步闭环，缺一不可；composer.json需手动写对name（小写vendor/package）、type（library）、autoload（PSR-4双反斜杠）等字段，tag须带v前缀并git push --tags，Packagist首次需手动提交仓库URL触发抓取，最后须本地验证安装与类加载。
本地写完代码不能直接发布，必须走完“规范配置 → 打 tag → Packagist 提交 → 验证安装”四步闭环，漏任何一环都会导致别人 composer require 失败。
composer.json 必须手动写对，别信 composer init 的默认值
默认生成的 composer.json 几乎没用：缺 name、type、autoload，或者 name 里带大写字母/下划线，Packagist 直接拒收。
-
name必须是小写vendor/package格式，比如qh4-module/user-service，且vendor要和你在 Packagist 的用户名一致 -
type建议设为library，不是project（后者会被 Packagist 当作应用，不推荐分发） -
autoload用 PSR-4，注意末尾反斜杠："Qh4Module\UserService\": "src/"，少一个就会导致类找不到 - 加
license字段（如"MIT"），否则 Packagist 页面会标黄警告
Git tag 不是可选项，而是 Packagist 识别版本的唯一依据
Packagist 不读 main 分支，只认 Git tag。没 tag，composer require 就只能看到 dev-main，装不了正式版。
- tag 名必须带
v前缀，如v1.0.0，1.0.0或release/1.0.0都不会被识别 - 打完 tag 后必须
git push --tags，只git push不推 tag = 白干 - 确认 GitHub/GitLab 页面能点开
v1.0.0标签，且能看到对应 commit 和完整的composer.json - 改错 tag？别删重打——Git tag 不可变，Packagist 也不会刷新，得去后台点 “Update”
Packagist 提交后不是自动同步，首次必须手动触发抓取
Packagist 不会轮询你的仓库，你提交 URL 后它才第一次抓取。后续 tag 推送才会自动更新，但前提是首次成功。
- 登录 Packagist → 右上角 “Submit” → 粘贴仓库 HTTPS 地址（如
https://github.com/qh4-module/user-service） - 如果失败，页面会直接显示原因：常见是
Repository not found（私有库）、Invalid package information（composer.json缺字段或格式错） - 成功后，包页会列出已抓到的 tag；没看到
v1.0.0？回去检查 tag 是否推送成功、composer.json是否在该 commit 中 - 别勾选 “Auto-update” 以外的选项，私有库必须换方案（如 Satis）
本地验证安装比等用户反馈快十倍
别等别人报 Could not find package 或 Class not found，自己先跑一遍真实流程。
- 新建空目录：
mkdir test-app && cd test-app && composer init -n - 临时装 dev 分支验证结构：
composer require qh4-module/user-service:dev-main（不用等 Packagist 同步） - 再试正式版：
composer require qh4-module/user-service:^1.0，看是否拉到v1.0.0 - 进
vendor/qh4-module/user-service，执行composer dump-autoload -o，然后写个测试脚本new Qh4ModuleUserServiceSomeClass()看是否真能实例化
最容易被忽略的是 autoload 路径映射和 tag 推送动作的分离——写对了 composer.json，也打了 v1.0.0，但忘了 git push --tags，整个发布链就断在第一步。
