Composer install 不会自动触发 PHPDoc 生成，因其仅负责依赖管理与脚本执行；PHPDoc 是独立工具，需通过 composer.json 的 scripts 显式配置（如 "docs" 命令）并手动运行，或结合 phpdoc.xml 配置调用。
为什么 composer install 不会自动触发 PHPDoc 生成
Composer 本身不处理文档生成，它只管依赖安装和脚本执行。PHPDoc（如 phpdocumentor）是独立工具，需要显式调用或通过 Composer 脚本绑定。常见误解是以为加了 require-dev 就能自动生成文档——其实只是把工具装进 vendor/bin/，后续步骤全靠手动或配置驱动。
真正起作用的是 composer.json 中的 scripts 段，它让 composer run docs 这类命令成为可能。
- PHPDoc 工具（如
phpdocumentor/phpdocumentor）必须放在require-dev里，否则vendor/bin/phpdoc不会出现 - 不能依赖
post-install-cmd自动跑文档生成——开发环境每次composer install都生成一次文档，既慢又没必要 -
phpdoc命令默认不读取composer.json，需额外配置phpdoc.xml或用--directory指定源码路径
如何用 Composer 脚本一键运行 phpdocumentor
在 composer.json 的 scripts 下添加自定义命令，是最轻量、最可复用的方式。这样团队成员只需执行一条命令，无需记参数或路径。
示例配置（支持 PHP 8.0+ 和 phpdocumentor v3）：
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
立即学习“PHP免费学习笔记（深入）”；
"scripts": {
"docs": [
"php -d memory_limit=-1 vendor/bin/phpdoc --config=phpdoc.xml"
],
"docs:watch": "php -d memory_limit=-1 vendor/bin/phpdoc --config=phpdoc.xml --force --quiet --template=clean"
}
-
memory_limit=-1很关键：大型项目解析注释容易 OOM，尤其含大量 trait 或泛型模拟注释时 -
--config=phpdoc.xml推荐使用配置文件而非长命令行，便于维护路径、忽略目录、模板选择等 -
--force强制重生成（避免缓存导致文档未更新），--quiet减少干扰输出 - 不要把
docs放进post-autoload-dump——每次composer dump-autoload都跑一遍文档，纯属浪费时间
phpdoc.xml 配置里最容易错的三处
phpdoc.xml 是 phpdocumentor v3 的标准配置，但很多用户复制旧模板后卡在路径、版本或插件上。核心不是“写全”，而是确保三处匹配真实项目结构。
-
<paths><source>./src</source></paths>：必须指向实际 PHP 类所在目录，不是./或./app；若用 Laravel，通常应为./app或./src，而非./vendor -
<version number="*"/>：设成*才会按composer.json的version字段自动填入文档页眉；设成固定字符串（如"1.0"）会导致版本硬编码，后续发版要手动改 -
<transformations>中若启用了psalm或phpstan插件，但项目没装对应分析器，phpdoc会静默失败或报Class not found错误——先删掉插件段再逐步加回
生成的文档打不开？检查 output 目录权限和 URL 路径
phpdocumentor 默认输出到 ./output，但直接双击 index.html 会因浏览器同源策略报 JS 加载失败（Failed to load resource: net::ERR_FILE_NOT_FOUND）。这不是代码问题，是本地文件协议限制。
- 正确做法：用简易 HTTP 服务预览，例如
cd output && php -S localhost:8000 - 若部署到 Nginx/Apache，确保
output目录被设为 web root 子目录（如/var/www/html/docs），且index.html可被直接访问 - 生成后检查
output/.buildinfo文件是否存在——没有它说明构建中途退出，大概率是某处 PHPDoc 注释语法错误（如@param $foo string缺少变量名） - CI 环境中记得加
--no-interaction参数，否则phpdoc可能卡在交互式确认上
复杂点在于：PHPDoc 注释质量直接影响输出结构，而 Composer 只负责调起工具——它不管你的 @return 写的是 array 还是 MyCollection<User>。工具能跑通，不等于文档有用。
