phpdoc 不生效主因是未正确加载 Composer autoloader 或路径配置错误；需显式指定 --directory、--target，配置 phpdoc.xml 的 paths 和命名空间，并确保注释类型书写规范。
composer install 后 phpdoc 不生效？先确认 autoloader 是否加载了注释
phpDocumentor（phpdoc）本身不依赖 Composer，但它的解析能力严重依赖类的自动加载机制。如果你用 composer install 安装了项目，但 phpdoc 扫描时提示“找不到类”或大量 @var 无法解析，大概率是它没走 Composer 的 autoload.php。
实操建议：
- 运行
phpdoc时必须显式指定--directory和--target，且确保--directory指向实际含 PHP 类文件的路径（不是vendor/） - 加
--visibility-level public避免因默认只扫 public 成员而漏掉重要方法 - 若项目用了 PSR-4 自动加载，务必在
phpdoc.xml中配置<paths><path>src/</path></paths>，而不是依赖扫描根目录 - 别直接在
vendor/bin/phpdoc目录下执行 —— 它会把当前路径当项目根，导致 autoload 失效
phpdoc 命令行参数和 composer.json 的关系很弱
Composer 只管包管理与自动加载，phpdoc 是独立工具。你在 composer.json 里写 "phpdocumentor/phpdocumentor": "^3"，只是把它装进 vendor/bin/，不会自动绑定配置或触发生成。
常见错误现象：
立即学习“PHP免费学习笔记（深入）”；
- 改了
composer.json的autoload段，但没运行composer dump-autoload，phpdoc 就读不到新类路径 - 误以为加了
"scripts": {"docs": "phpdoc"}就能一键生成 —— 实际要补全参数，比如"docs": "phpdoc --directory=src --target=docs/api" - 用
phpdoc run却没配phpdoc.xml，结果按默认规则扫了整个项目（包括tests/和vendor/），耗时长还报错
phpdoc v3 生成 HTML 文档失败？检查模板和 PHP 版本兼容性
phpdoc v3 默认使用 clever-style 模板，但它要求 PHP ≥ 8.0；如果你用的是 PHP 7.4，就会卡在 Template 'clever-style' not found 或空白输出。
解决路径很直接：
- 降级模板：加参数
--template="phpdoc-theme"（这是 v3 内置的兼容模板） - 或者明确指定旧版：用
phpdocumentor/phpdocumentor:2.9.2（v2 支持 PHP 7.2+，命令也略有不同：phpdoc -d src -t docs/api） - v3 的
phpdoc.xml必须声明xmlns="https://www.phpdoc.org"，少这个命名空间会导致解析失败，但错误提示极不明显 - 生成后检查
docs/api/index.html是否真有内容 —— 有时成功返回但输出目录为空，大概率是--directory路径写错了（比如写了./src但实际是src/）
注释写法影响生成质量：@param/@return/@throws 不是可选装饰
phpdoc 工具不会“猜”类型。你写 /** @param $id */，生成的文档里参数类型就是 mixed；而 /** @param int $id */ 才会标成 int。这对 IDE 提示和静态分析更重要，但文档可读性也直接受损。
容易被忽略的细节：
-
@param后必须跟类型，再跟变量名，顺序不能反（@param string $name✅，@param $name string❌） - 数组类型写
string[]或array<string></string>都行，但别用array—— 它不会展开元素类型 - 返回 void 的方法，必须写
@return void，否则 phpdoc 可能推成mixed并显示“Returns”标题 - 如果用了 PHP 8.0+ 的联合类型（如
string|int），phpdoc v3 能识别，但 v2 会直接报错退出
文档能不能看懂，一半靠工具，一半靠注释有没有真写清楚。类型写错、漏写 @return、把 @var 当 @param 用，都会让生成结果变成“正确但无用”。
