Composer scripts 不能自动生成 API 文档，本质是封装 phpDocumentor 等工具；需正确安装、用 @php 调用 vendor/bin/phpdoc，检查 ext-zip、PHP≥8.1、memory_limit，并显式指定配置文件和路径。
Composer 本身不生成文档，scripts 字段也不能直接“自动生成 API 文档”——所谓“文档自动生成脚本”，本质是把已有文档工具（如 phpDocumentor、phpstan、apidoc）封装进 composer.json 的 scripts，让它能被 composer run 统一调用。配错位置、路径或执行上下文，脚本就静默失败或报 Class not found。
为什么 phpdoc 命令在 scripts 里总报 command not found
常见错误是直接写 "docs:generate": "phpdoc -d src -t docs/api"，但 phpdoc 不在系统 $PATH，也没通过 vendor/bin/ 暴露。
- phpDocumentor v3+ 已改用
phpdoc命令，但默认不安装到vendor/bin/；必须显式composer require --dev phpdocumentor/phpdocumentor才会注册可执行文件 - 确认命令存在：
ls -l vendor/bin/phpdoc，不存在就说明没装对或版本不兼容 - 别用全局
phpdoc：CI 环境通常没装，且 PHP 版本、扩展（如ext-zip）可能不匹配 - 正确写法：
"docs:generate": "@php vendor/bin/phpdoc -d src -t docs/api --force"，用@php确保调用当前项目 PHP，--force避免因缓存拒绝重建
如何让文档生成脚本支持多环境输出格式
phpDocumentor 支持 clean、html、xml、json 等多种目标，但 scripts 不支持条件分支，得靠参数透传或拆成多个脚本。
- 单脚本 + 参数透传（推荐）：
"docs:generate": "@php vendor/bin/phpdoc --template=clean --target=docs/api --force"，运行时用composer run docs:generate -- --template=bootstrap --target=docs/api-bootstrap - 避免硬编码路径：用
${PWD}锚定输出目录，比如--target=${PWD}/docs/api，防止在子目录中执行时写错位置 - 若需同时生成 HTML 和 XML，不要写成一条命令拼接（
&&易中断），改用数组："docs:generate": ["@php vendor/bin/phpdoc -t ${PWD}/docs/api-html", "@php vendor/bin/phpdoc -t ${PWD}/docs/api-xml --format=xml"]
生成文档前必须检查的三项依赖
phpDocumentor 运行失败，90% 出在底层依赖缺失，不是配置问题。
-
ext-zip：v3+ 必需，用于解压模板资源；composer install时若提示The zip extension is missing，得先装系统包（如 Ubuntu 的php-zip）再重试 -
php >= 8.1：phpDocumentor v3 要求 PHP 8.1+，但项目自身可能只用 PHP 7.4 —— 脚本运行环境必须独立满足，不能复用项目 PHP 版本约束 -
memory_limit：大型代码库生成文档常 OOM；脚本里必须加-d memory_limit=-1，例如："@php -d memory_limit=-1 vendor/bin/phpdoc -d src -t docs/api"
最易被忽略的是工作目录和权限：脚本运行时 CWD 是 composer.json 所在目录，但 vendor/bin/phpdoc 内部可能读取相对路径的配置文件（如 phpdoc.xml）。如果没放对位置，它会静默降级为默认行为，生成空文档或漏类 —— 建议始终显式用 --config=phpdoc.xml 指定配置，而不是依赖自动发现。
