Flutter Web部署GitHub Pages遇字体加载错误及空白页求助

以下是针对该问题的具体解决步骤：

• 修正pubspec.yaml的字体配置
  检查pubspec中cupertino_icons的字体声明，确保路径没有多余的引号或格式错误：

  cupertino_icons: ^1.0.6
  
  fonts:
    - family: CupertinoIcons
      fonts:
        - asset: packages/cupertino_icons/CupertinoIcons.ttf
  

  避免在asset路径中添加不必要的引号，这会导致部署后解析路径时出现语法错误。

• 构建时指定正确的base-href参数
  GitHub Pages部署需要匹配仓库路径，构建命令必须加上--base-href参数，替换为你的仓库名称：

  - name: Build Flutter Web
    run: flutter build web --release --base-href "/你的仓库名称/"
  

  缺失或错误的base路径会导致所有静态资源（包括字体）加载路径错位，引发空白页面和资源加载失败。

• 确认GitHub Pages部署源设置
  进入仓库的「Settings」→「Pages」页面，确保部署源选择的是gh-pages分支的/root目录，不要选择/docs或其他子目录，防止资源路径匹配错误。

• 彻底清理缓存后重新构建
  在GitHub Actions工作流中补充完整的清理和依赖安装步骤，避免旧缓存干扰：

  - name: Clean project and install dependencies
    run: |
      flutter clean
      flutter pub get
      flutter pub upgrade
  

• 排查资源加载路径
  部署后打开浏览器开发者工具（F12），切换到「Network」标签，查找CupertinoIcons.ttf的请求记录：

  • 如果返回404，说明路径配置错误，调整--base-href或pubspec中的asset路径；
  • 如果请求路径包含非法字符，检查pubspec的字体配置是否有多余符号。

内容的提问来源于stack exchange，提问作者Louis P.