phpstorm不直接生成文档，仅调用命令行工具；右键“generate php documentation”无反应，主因是路径错误、输出目录未创建或选中非目录项，需确保phpdoc路径正确、docs/api存在且选中src等有效目录。
PhpStorm 本身不运行 phpDocumentor、ApiGen 或 swagger-php，它只负责调用命令行工具——真正生成文档的是你装在项目里或系统里的可执行文件。如果右键“Generate PHP Documentation”后没反应、报错或输出空目录，问题几乎都出在路径、权限或注释结构上。
为什么右键 Generate PHP Documentation 没反应
这个菜单项本质是调用你填在 Settings > Other Settings > PHP > Documentation 里的可执行路径，然后传入当前选中的目录作为源码路径。常见失败原因：
-
phpdoc或apigen命令不在 PATH 中，且你填的路径错误（比如写成phpdoc而不是./vendor/bin/phpdoc） - 输出目录不存在，phpDocumentor 不会自动创建，静默跳过（必须先
mkdir -p docs/api） - 选中的是单个 PHP 文件，但工具默认只处理目录；或者选中了
vendor/这类排除目录 - PHP 版本不兼容：ApiGen 已停止维护，
apigen/apigen:^4.1最高只支持 PHP 7.4，PHP 8.0+ 会直接报ParseError
用 Composer 安装 phpDocumentor（推荐）
phpDocumentor 是目前唯一持续更新、兼容 PHP 8.0–8.5 的主流原生文档生成器，适合交付内部技术文档。不要用全局安装，避免版本冲突：
- 项目内安装：
composer require --dev phpdocumentor/phpdocumentor - 初始化配置：
./vendor/bin/phpdoc --initialize，会生成phpdoc.xml - 编辑
phpdoc.xml，确认<directory>./src</directory>和<output>docs/api</output>正确 - PhpStorm 中填入路径：
./vendor/bin/phpdoc（Linux/macOS）或./vendor/bin/phpdoc.bat（Windows）
ApiGen 已不可用，别再试了
ApiGen 自 2019 年起停止维护，其最后稳定版 apigen/apigen:^4.1 在 PHP 8.0+ 下无法启动，会卡在 Class "TokenReflection\IReflection" not found。即使强行降级到 PHP 7.4，也会因缺少 ext-tokenizer 或 ext-dom 报错。官方 GitHub 仓库已归档，无任何后续更新计划。
如果你看到网上教程还在推 ApiGen，请直接跳过。替代方案只有两个：
- phpDocumentor（HTML 文档，吃标准 PHPDoc）
- swagger-php（OpenAPI JSON/YAML，需加
@OA\Get等注解）
生成前必须检查的三件事
无论用哪个工具，只要这三点没做对，生成结果一定残缺或空白：
- 光标必须放在
function或class关键字正前方才能触发/** + Enter—— 放在函数名后、花括号里、空行上都不行 -
__invoke()、__toString()这类魔术方法默认不生成 PHPDoc，要手动开启：Settings > Editor > Inspections > PHP > PHPDoc > Missing PHPDoc > Treat __invoke as documented method - 闭包、
trait方法、类属性不支持自动生成，必须手写/** @var string $name */或/** @method void run() */
最常被忽略的是注释位置和魔术方法识别开关——这两个点一错，整个项目的 PHPDoc 就断层，后续所有文档工具都只能抓到空壳。工具链再新，也救不了没写对的基础注释。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
