Flutter Web使用GoRouter带参数路径直接访问浏览器显示空白页问题

核心原因 #

直接在浏览器地址栏输入/article/1234这类动态路由时，Web服务器会默认寻找对应物理路径的资源，找不到就返回空白页。但Flutter是单页应用，所有路由逻辑都需要由GoRouter处理，因此需要服务器将所有路由请求转发到index.html。

具体解决步骤 #

1. 配置Web服务器的路由 fallback #

• 本地Apache服务器：
  在项目web目录下创建.htaccess文件，添加以下内容：

  <IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteBase /
    RewriteRule ^index\.html$ - [L]
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule . /index.html [L]
  </IfModule>
  

• Nginx服务器：
  在Nginx配置文件中添加路由转发规则：

  location / {
    try_files $uri $uri/ /index.html;
  }
  

• Firebase Hosting部署：
  修改firebase.json的rewrites配置：

  {
    "hosting": {
      "public": "build/web",
      "rewrites": [
        {
          "source": "**",
          "destination": "/index.html"
        }
      ]
    }
  }
  

2. 确保GoRouter初始化正确 #

确认GoRouter实例全局可用，且在MaterialApp中正确绑定：

final GoRouter _router = GoRouter(
  routes: [
    GoRoute(
      path: '/',
      builder: (context, state) => HomeScreen(),
    ),
    GoRoute(
      path: "/article/:id",
      builder:(context,state) => ArticleScreen(id:state.params['id']!),
    ),
  ],
);

// 全局使用
MaterialApp.router(
  routerConfig: _router,
);

注意：对state.params['id']做非空处理，避免因参数为空导致页面渲染失败。

3. 本地开发临时调试方案 #

启动项目时添加--web-history-api-fallback参数，让Chrome自动处理路由转发：

flutter run -d chrome --web-history-api-fallback

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