私有 Composer 包文档需人工同步：README 必置根目录并含完整安装命令、配置示例、环境变量及错误码；API 文档须绑定 Git tag 并提交至仓库；support.docs 必须指向带版本号的可访问 URL，且 CI 需校验部署结果。
私有 Composer 包的文档不随 composer install 自动拉取，也没有内置文档同步机制；必须靠人工维护 README、生成 API 文档、显式托管并更新 support.docs 字段——漏掉任一环节，团队就查不到最新用法。
README 必须放在包根目录且覆盖真实使用场景
这是开发者打开包后第一眼看到的内容，不能只写“本包用于 xxx”，要直奔主题：
- 明确写出
composer require vendor/package-name的完整命令（含私有仓库前缀，如my-internal-repo/vendor/package-name） - 配置示例必须可复制粘贴：比如 Laravel 中如何注册服务提供者、Lumen 中怎么手动加载，
config/xxx.php文件路径是否需手动创建 - 环境变量依赖要列全：
XXX_API_KEY、XXX_TIMEOUT，并标注默认值和必填项 - 错误码表直接嵌入，不要写“详见文档”——90% 的人不会点开链接，只扫 README
PHPDoc 生成的 API 文档必须绑定 Git tag
用 phpdoc 或 sami 生成的 HTML 文档，如果没跟版本对齐，就会出现“文档写着 v2.1.0 接口，实际装的是 v2.0.0 却报错”的情况：
- 每次发布新 tag 前，先在对应 commit 上运行
phpdoc run -d src -t docs/api（或你配置的输出路径） - 生成的
docs/api/目录应提交进 Git，和代码一起打 tag —— 不要只生成不提交，也不要生成到vendor/下 - CI 流水线里加一步校验：
git ls-tree -r v${VERSION} -- docs/api/index.html，确保 tag 里真有文档文件 - 避免用相对路径链接：文档中所有跳转链接必须是绝对路径（如
/api/v2.1.0/MyClass.html），否则部署到子路径时 404
support.docs 字段必须指向可访问、带版本路径的 URL
这个字段不是装饰，是 IDE 和工具链（如 PHPStorm 的 “Go to Documentation”）唯一能自动识别的入口：
- URL 格式必须含版本号，例如
"https://docs.internal.company/my-package/v2.1.0"，不能是.../latest或.../main - 服务器需支持按路径路由：请求
/v2.1.0时返回该 tag 对应的静态文档，而非重定向到首页 - 修改
composer.json后必须重新提交到 Packagist（或私有 Satis）——它不会自动读取新字段，得手动点 “Update” - 测试方法：在另一个项目里执行
composer show vendor/package-name，确认输出里support行显示的是你刚设的 URL
私有文档站别依赖 “自动同步”，要显式触发部署
内部 Wiki 或静态站点（如 Docusaurus）不会监听 Git tag 变更，所谓“自动”只是把 CI 脚本写进 post-release：
-
post-release脚本里不能只写git push --tags，还得加：rsync -avz docs/api/ user@docs-server:/var/www/docs/my-package/v${VERSION}/ - 若用 Confluence，得调用 REST API 上传页面，且注意空间权限——很多失败是因为 bot 账号没编辑权限
- 最关键的一点：文档部署失败不能静默吞掉。脚本末尾加
curl -f https://docs.internal.company/my-package/v${VERSION}/index.html验证 HTTP 200，失败就 exit 1
最常被忽略的不是技术细节，而是文档和代码的版本边界——文档没打 tag，就等于没发布；support.docs 指向的路径不存在，就等于没上线。别信“推了就能查”，每个环节都要人工或脚本验证一次。
