Flutter运行build_runner构建时提示build.dart预编译失败错误

运行build_runner系列指令（代码生成、构建watch等）时抛出如下错误：

Failed to precompile build script .dart_tool/build/entrypoint/build.dart.

按优先级从高到低执行以下排查修复操作：

• 清理损坏的本地构建缓存
  增量构建缓存损坏是该报错的最高频诱因，按顺序执行命令：

  # 清理build_runner生成的临时构建文件
  dart run build_runner clean
  # 删除.dart_tool下损坏的构建入口缓存
  rm -rf .dart_tool/build
  # 重新拉取项目依赖
  flutter pub get
  

  执行完成后重新运行原构建指令，验证问题是否修复。
• 排查依赖版本冲突
  build_runner和关联的代码生成插件（json_serializable、freezed、retrofit_generator等）版本不兼容、和当前Dart/Flutter SDK版本不匹配时，也会触发脚本预编译失败：
  1. 执行flutter pub outdated查看依赖版本适配提示，将所有build系dev依赖统一为兼容的大版本，避免混用2.x和1.x版本的生成器插件。
  2. 不确定适配版本时，可直接升级build_runner到最新稳定版：

     flutter pub upgrade build_runner
     

  3. 重新执行flutter pub get拉取适配版本的依赖后重试构建。
• 修复Pub全局缓存损坏
  本地Pub缓存中的包文件损坏、下载不完整时，会导致构建脚本预编译失败，执行命令修复全局缓存：

  flutter pub cache repair
  

  该命令会重新拉取本地缓存的所有Pub包修复损坏文件，执行完成后重新拉取项目依赖再尝试构建。
• 清理版本切换残留配置
  如果近期有切换Flutter渠道、升级/降级Flutter大版本的操作，残留的旧版本配置会导致构建异常，直接删除锁定文件和工具目录后重新初始化：

  rm -rf .dart_tool pubspec.lock
  flutter pub get
  

• 检查路径与权限问题
  项目所在本地路径包含中文、空格、特殊转义字符，或者项目放在系统权限受限目录（如Windows下的C:\Program Files目录、macOS/Linux下的root权限目录）时，会因为脚本读写权限不足、路径解析失败触发报错，将项目移动到无特殊字符的普通用户目录下再执行构建即可。

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