php think help 找不到自定义命令是因为未在app/command.php中注册，需手动添加如'gen:doc' => app\command\GenDoc::class；类须继承ConsoleCommand或Command，且文件名与类名一致。
为什么 php think help 找不到你的自定义命令
ThinkPHP 的命令行扩展默认不会自动加载 app/command/ 下的类，必须显式注册。不注册就运行不了，连报错都看不到——它直接当命令不存在。
- 确保类继承
think\ConsoleCommand（TP6.1+）或think\command\Command（TP6.0） - 类名必须与文件名一致，且首字母大写，比如
GenDoc.php里是class GenDoc - 在
app/command.php配置文件中手动添加：return ['gen:doc' => app\command\GenDoc::class]; - TP6.1 后支持注解注册，但需开启
console_annotation配置，不如配置数组稳定
Schema::getSchema() 拿不到字段注释？检查驱动和权限
MySQL 8.0+ 默认关闭 information_schema 的列注释读取权限，PDO 查询 COLUMNS 表时会静默丢掉 column_comment 字段。
- 确认数据库用户有
SELECT权限访问information_schema.COLUMNS - 用原生 SQL 测试：
SELECT column_name, column_comment FROM information_schema.COLUMNS WHERE table_schema = 'your_db' AND table_name = 'user'; - TP6 的
Schema类不兼容 MariaDB 的COMMENT字段别名，建议统一用 MySQL 官方驱动 - 字段类型映射靠
think\db\builder\Mysql::getFieldsType()，自定义类型需重写该方法或 patch builder
生成 Markdown 文档时中文表名乱码或换行错乱
核心问题是 PHP file_put_contents() 默认用 UTF-8 without BOM，但某些编辑器（如老版 VS Code、Typora）对无 BOM 的 UTF-8 解析异常，尤其含中文表名或字段注释时。
- 写入前加 BOM 头：
file_put_contents($path, "\xEF\xBB\xBF" . $content); - 表名/字段名中的下划线不要自动转空格，保持原始命名，否则和代码对不上
- 字段注释里含
|或换行符会破坏 Markdown 表格结构，先用str_replace(['|', "\n"], ['\|', ' '], $comment)转义 - 避免用
print_r()直接 dump 结构，它不保证字段顺序，应基于SHOW FULL COLUMNS FROM结果构建数组
如何让文档包含索引页和关联关系说明
单纯遍历表生成单文件不够用，真实项目需要跨表理解。TP 自身不提供外键元数据提取，得自己查 information_schema.KEY_COLUMN_USAGE。
立即学习“PHP免费学习笔记（深入）”；
- 用原生查询拼出外键关系：
SELECT TABLE_NAME, COLUMN_NAME, REFERENCED_TABLE_NAME, REFERENCED_COLUMN_NAME FROM information_schema.KEY_COLUMN_USAGE WHERE TABLE_SCHEMA = ? AND REFERENCED_TABLE_NAME IS NOT NULL - 把结果组织成
['user' => [['field' => 'dept_id', 'ref_table' => 'dept', 'ref_field' => 'id']]]格式，再注入到模板 - 索引页用
glob('runtime/doc/*.md')扫描生成，注意排除_index.md自身 - 生成完记得
chmod 644输出目录下的文件，避免部署后因权限问题无法读取
最麻烦的不是生成逻辑，而是每次 DB 变更后忘记重新跑命令；建议把它塞进 migration 的 afterUp 钩子，或者 Git 提交前的 husky 脚本里——但别依赖 IDE 自动触发，那根本不可靠。
