私有包发布前必须验证三件事：一、运行 composer validate 确保 composer.json 合法；二、git tag 必须为纯语义化格式（如 v1.0.0）并显式推送；三、确认 commit 已含最终版 composer.json，否则 packagist 抓取失败。
私有包发布前必须验证的三件事
不验证就推 tag，90% 的失败都发生在这一步。Packagist 不会帮你校验 composer.json 合法性，CI 也不会替你读文档。
-
composer validate必须在 CI 流水线最前端运行——它能提前暴露字段缺失、name 格式错误（如含大写字母或下划线）、autoload 路径不存在等问题 - 确保 Git tag 名字是纯语义化格式：
v1.0.0✅，1.0.0❌，V1.0.0❌，release/v1.0.0❌；且必须用git push origin v1.0.0显式推送，git push --tags容易漏推 - 打 tag 的那个 commit 必须已包含最终版
composer.json，否则 Packagist 抓到的是空配置或旧版本，报错信息常为Could not fetch package info或页面显示Last updated: 3 days ago却无新版本
GitHub Webhook 配置失效的典型表现与修复
没配好 webhook，等于没发布。Packagist 自 2023 年底起完全依赖它感知新 tag，手动点 Update 只能救急，不能替代。
Discussion Composer
下载
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 现象：push 了
v2.0.0，但 Packagist 包页仍显示dev-main或上一个旧版本，Last updated时间未刷新 - 检查路径：GitHub 仓库 → Settings → Webhooks → Add webhook，Payload URL 填
https://packagist.org/api/github（不是 php.cn 域名） - Event 类型必须勾选 Tag push events，仅选 Just the push event 不够——因为默认 push 不包含 tag
- 验证是否通：点开 Recent Deliveries，找最新一条，Status code 是
200才算成功；4xx/5xx 需检查 URL 拼写或权限（私有仓库无法被索引）
CI 中如何安全触发 Satis 构建并避免缓存污染
Satis 构建不是“跑完就完”，它依赖远程 Git 仓库状态和本地缓存，CI 环境下容易因 workspace 复用导致构建结果陈旧或失败。
- 每次构建前加清理步骤：
rm -rf satis.json public/ && git clone https://git.yourcompany.com/satis-config.git .，避免残留旧satis.json或 stalepublic/ - 构建命令必须指定
--no-interaction和--skip-errors：php bin/satis build satis.json public/ --no-interaction --skip-errors，否则遇到某个私有包不可达时整个流程中断 - 上传 public/ 到静态服务（如 Nginx）后，建议加 HTTP 头校验：
curl -I https://packages.yourcompany.com/packages.json | grep "HTTP/2 200"，防止构建成功但文件未生效 - 别把 Satis 构建和测试混在同一个 job：先跑
phpunit，再跑satis build，否则测试失败却仍更新了仓库，下游项目会拉到未验证的代码
用户端 require 私有包时最常见的加载失败原因
即使你发包成功、Satis 构建正常、webhook 也通了，用户执行 composer require your-company/your-package 仍可能失败——问题往往不在你这，而在他们本地环境。
- 目标项目
composer.json中没声明私有仓库："repositories": [{"type": "composer", "url": "https://packages.yourcompany.com"}]，缺这一行就会 fallback 到 Packagist，报Could not find package your-company/your-package - 用户机器未配置私有源认证（尤其用 HTTPS + Basic Auth 的场景）：
COMPOSER_AUTH='{"http-basic": {"packages.yourcompany.com": {"username": "xxx", "password": "xxx"}}}' composer install必须设环境变量，不能只靠config.json - PHP 版本或扩展不满足要求：比如你的包 require
ext-redis，而用户环境没启用，composer install不报错，但运行时报Class 'Redis' not found——这种得靠require-dev里加phpunit+ 全量扩展检测脚本提前拦截
