如何在Flutter Web项目中通过Firebase Hosting配置Dart编写的自定义404页面

可行解决方案 #

第一步：修正Flutter侧路由配置

你之前的配置缺少路径传递兜底，直接通过浏览器输入的未匹配路径无法触发onUnknownRoute，按以下方式调整：

1. 入口处强制启用Path路由策略，在main.dart的runApp执行前添加配置：

import 'package:flutter/material.dart';
import 'package:flutter_web_plugins/flutter_web_plugins.dart';

void main() {
  // 启用PathUrlStrategy，移除URL中的#号
  usePathUrlStrategy();
  runApp(const MyApp());
}

2. 补全MaterialApp的路由兜底逻辑，保留双重校验，同时不要同时配置home属性避免路由冲突：

MaterialApp(
  debugShowCheckedModeBanner: false,
  initialRoute: "/",
  routes: {
    "/": (context) => const HomePage(),
    "/test": (context) => const TestPage()
  },
  // 主路由兜底，所有未在routes中注册的路径都会走到这里
  onGenerateRoute: (settings) {
    // 必须传入settings保留路径信息
    return MaterialPageRoute(
      settings: settings,
      builder: (_) => const NotFoundPage(), // 替换为你自己用Dart写的404页面
    );
  },
  // 异常场景兜底，避免极端情况路由失效
  onUnknownRoute: (settings) {
    return MaterialPageRoute(
      builder: (_) => const NotFoundPage(),
    );
  },
)

第二步：调整Firebase Hosting配置

你之前的rewrite规则只会把所有请求返回200状态的index.html，未匹配路径默认会触发Firebase自带的404页面，修改firebase.json添加404页面指定：

{
  "hosting": {
    "cleanUrls": true,
    "public": "build/web",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ],
    "rewrites": [
      {
        "source": "**",
        "destination": "/index.html"
      }
    ],
    // 新增配置：指定404页面为Flutter入口文件，让Flutter接管路由逻辑
    "404": "/index.html"
  }
}

第三步：重新构建部署

每次部署前清理旧构建缓存，避免旧文件残留导致失效：

flutter clean
flutter build web --release
firebase deploy

配置完成后，所有未匹配的路径都会返回404状态码，同时加载Flutter的入口文件，触发你配置的路由兜底逻辑，展示Dart编写的自定义404页面。 #

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