composer install 不该自动生成文档，因 post-install-cmd 执行时机过早、环境不全易失败；应改用手动 scripts 命令如 "docs"，配合 phpdoc.xml 正确配置路径、排除项和内存限制。
composer install 不会、也不该自动生成文档。强行绑定 post-install-cmd 会导致 CI/CD 卡顿、部署失败、路径解析错误，这不是配置问题，而是职责错位。
为什么 post-install-cmd 跑不起来 phpdoc
常见报错是 command not found: phpdoc 或 Class not found，根本原因不是命令写错，而是执行时机和环境错配：
-
post-install-cmd在vendor/尚未完全写入、autoload 还没刷新时就触发，vendor/bin/phpdoc可能还没生成或不可执行 - PHP 扩展缺失（如
xml、mbstring）或内存不足（默认memory_limit=128M），而文档工具常需-d memory_limit=-1 - Windows 下
vendor/bin/phpdoc实际是phpdoc.bat，直接调用 shell 命令会失败 - 路径含空格（如
C:\Program Files\）时，system()或 shell 模式解析崩溃
scripts 里怎么写 docs 命令才可靠
把文档生成当作明确的开发动作，而不是安装副作用。推荐写法：
"scripts": {
"docs": [
"rm -rf docs/api",
"php -d memory_limit=-1 vendor/bin/phpdoc --config=phpdoc.xml"
],
"docs:doxygen": "doxygen Doxyfile"
}关键点：
Discussion Composer
下载
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 用数组写多步骤，避免
&&在 Windows 下失效 -
php -d memory_limit=-1显式提内存，防 OOM 中断 -
docs:doxygen不走 Composer 管理，得确保系统级doxygen在$PATH中 - 命令名用
docs，不是generate-docs——短、易记、社区通用
phpdoc.xml 里三处填错就白跑
phpdocumentor v3 强依赖 phpdoc.xml，但模板里常埋坑：
-
<fileset>必须包裹<directory>，单独写<directory>会被忽略 -
<directory>的path是相对于phpdoc.xml所在位置，不是项目根目录；比如phpdoc.xml在根目录，那path="src"才对 -
<exclude>必须显式列出Tests、Fixtures、vendor，否则扫描失败或文档混入测试类
最小可用片段示例：
<phpdocumentor>
<paths>
<output>docs/api</output>
</paths>
<title>My Project Docs</title>
<version number=""></version>
<transformations>
<transformation writer="twig" format="html" output="docs/api"/>
</transformations>
<files>
<fileset>
<directory path="src"/>
<exclude>Tests/</exclude>
<exclude>Fixtures/</exclude>
<exclude>vendor/</exclude>
</fileset>
</files>
</phpdocumentor>中文注释本身不影响生成，但 phpdocumentor 默认只识别标准 DocBlock 格式（/*<em> ... </em>/），且不支持 UTF-8 BOM。插件配置不是重点——真正卡住的永远是路径、内存、排除规则这三处。别在 post-install-cmd 上纠缠，composer docs 手动跑一次，比自动但总失败强十倍。
