GitHub Actions中dart doc生成超长文件名致Git拉取失败

问题核心 #

在GitHub Action环境执行dart doc时，工具未识别项目为pub package，导致生成的文档文件名包含完整绝对路径（如file-___home_runner_work_my-project_my-project_project_lib开头），超出Windows文件名字符限制；而本地运行时，项目会被识别为package，生成基于lib子目录的短文件名。

解决方案 #

修改GitHub Action工作流步骤 #

确保先在项目根目录（含pubspec.yaml的目录）执行依赖获取，再运行dart doc：

sudo snap install flutter --classic
cd project
dart pub get
dart doc --output ../docs

或者使用GitHub Action的working-directory参数指定工作目录，让步骤更清晰：

- name: 安装Flutter
  run: sudo snap install flutter --classic
- name: 获取项目依赖
  working-directory: project
  run: dart pub get
- name: 生成文档
  working-directory: project
  run: dart doc --output ../docs

原因说明 #

• 本地环境中，项目已通过pub get建立了pub package上下文，dart doc会使用package:project/main.dart这类路径生成文档，文件名仅保留lib下的相对路径。
• GitHub Action环境中，若未提前执行pub get，或未在正确的项目根目录运行dart doc，工具无法识别项目为合法的pub package，会回退使用文件的绝对路径生成文件名，最终导致文件名过长。

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