Flutter Web应用部署至服务器后直接访问子路由返回404问题求助

API 探路者

2026-10-19

问题根因

你使用setPathUrlStrategy()移除了Flutter Web URL默认的#锚点标识，此时所有路由路径都会变成普通路径格式。Flutter Web打包后仅存在一个index.html入口文件，所有路由都是前端侧的虚拟路由，直接访问子路径时服务器会尝试查找对应路径的静态资源，找不到就返回404错误。Debug模式正常是因为Flutter官方开发服务默认配置了路由回退规则。

解决步骤

1. 补全Flutter侧路由配置

你当前的路由配置缺少根路径/和全局未匹配路由的捕获规则，先修改AppModule代码：

import 'package:flutter_modular/flutter_modular.dart';
import 'package:package/main.dart';
import 'package:package/screens/loginPage.dart';
import 'package:package/screens/events.dart';
// 导入你的首页、404页面组件
import 'package:package/screens/home.dart';
import 'package:package/screens/not_found.dart';

class AppModule extends Module {
  @override
  final List<Bind> binds = [];

  @override
  final List<ModularRoute> routes = [
    // 补全根路径路由
    ChildRoute('/', child: (_, __) => HomePage()),
    ChildRoute('/login', child: (_, __) => LoginPage()),
    ChildRoute('/events/manage', child: (_, args) => Events(id: args.queryParams['user'])),
    // 新增全局未匹配路由捕获，可自定义404展示
    WildcardRoute(child: (_, __) => NotFoundPage()),
  ];
}

2. 配置服务器路由回退规则

所有指向你站点的请求都需要回退到index.html，交由Flutter路由处理路径匹配，不同部署环境配置如下：

Nginx部署：修改站点配置的location块，修改后重启Nginx生效

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

Apache部署：在站点根目录新建.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>

Vercel部署：在项目根目录新建vercel.json文件

{
  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}

Netlify部署：在项目根目录新建_redirects文件，添加如下规则

/*  /index.html  200

3. 重新部署验证

配置完成后执行flutter build web --release重新打包，将build/web目录下的产物上传到服务器，清除浏览器缓存后即可正常直接访问任意子路由，路由参数也可正常解析。

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