使用dartdoc生成Flutter项目文档时提示“Generation failed”

嘿，我明白你现在的困扰——不管用独立安装的Dart SDK还是Flutter自带的dartdoc，都卡在同一个错误上没法生成文档。我给你列几个实用的排查步骤，你可以一步步试：

• 先确保项目依赖全量拉取
  先在项目根目录执行flutter pub get（如果是Flutter项目）或者pub get（独立Dart环境），很多时候dartdoc失败是因为依赖没装全，解析不了相关类或库。

• 检查代码和注释的规范性
  dartdoc对注释格式和代码语法的要求挺严格的：

  • 先跑flutter analyze或者dart analyze扫描项目，修复所有语法错误、警告；
  • 检查有没有格式错误的注释，比如未闭合的/** ... */多行注释、拼写错误的dartdoc标签（比如把@param写成@pram）、注释里包含特殊字符导致解析失败。

• 开启 verbose 日志定位具体问题
  执行dartdoc的时候加上详细日志参数，能帮你精准找到出错的文件或代码段：

  # 独立Dart SDK的命令
  dartdoc --verbose --output ./docs
  # Flutter自带dartdoc的命令（替换成你的Flutter路径）
  path_to_flutter/flutter/bin/cache/dart-sdk/bin/dartdoc.bat --verbose --output ./docs
  

  日志里会显示dartdoc在处理哪个文件时崩溃，顺着这个线索去排查对应的代码或注释就行。

• 用最小项目测试工具是否正常
  新建一个干净的Flutter默认项目，只保留main.dart并加一段简单的dartdoc注释，比如：

  /// 主入口函数
  void main() {
    runApp(const MyApp());
  }
  

  然后用同样的dartdoc命令生成文档，如果能成功，说明问题出在你当前项目的某个文件或依赖上，你可以逐步把原项目的文件加进来测试，定位到具体的问题文件。

• 考虑升级Dart/Flutter版本
  你用的是非常早期的Dart 2.0.0-dev版本，这个阶段的dartdoc还很不成熟，有很多已知的bug和兼容性问题。建议你升级到稳定版的Dart SDK，或者直接更新Flutter到最新稳定版（Flutter自带的Dart SDK会同步更新），新版本的dartdoc修复了很多旧问题，大概率能解决你遇到的错误。

内容的提问来源于stack exchange，提问作者dedeswim