如何配置Fermyon Spin实现Flutter Web应用URL导航？

问题重现步骤 #

• 安装Flutter和Fermyon Spin
• 创建名为fermyon_routing_issue的Flutter应用，配置如下：
  • main.dart代码：

    import 'package:flutter/material.dart';
    import 'package:go_router/go_router.dart';
    import 'package:flutter_web_plugins/url_strategy.dart';
    
    final _router = GoRouter(
      routes: [
        GoRoute(
          path: '/',
          builder: (context, state) => const HomeScreen(),
          routes: [
            GoRoute(
              path: 'details',
              builder: (context, state) => const DetailsScreen(),
            ),
          ],
        ),
      ],
    );
    
    abstract class NamedScreen extends StatelessWidget {
      final String name;
      const NamedScreen({super.key, required this.name});
    
      @override
      Widget build(context) => Scaffold(body: Center(child: Text(name)));
    }
    
    final class HomeScreen extends NamedScreen {
      const HomeScreen({super.key, super.name = 'home'});
    }
    
    final class DetailsScreen extends NamedScreen {
      const DetailsScreen({super.key, super.name = 'details'});
    }
    
    void main() {
      usePathUrlStrategy();
      runApp(MaterialApp.router(routerConfig: _router));
    }
    

  • pubspec.yaml配置：

    name: fermyon_routing_issue
    description: "A new Flutter project."
    
    version: 1.0.0+1
    
    environment:
      sdk: '>=3.3.3 <4.0.0'
    
    dependencies:
      flutter:
        sdk: flutter
      flutter_web_plugins:
        sdk: flutter
      go_router: ^13.2.3
    
    dev_dependencies:
      flutter_test:
        sdk: flutter
      flutter_lints: ^3.0.0
    
    flutter:
      uses-material-design: true
    

• 执行flutter run -d chrome启动应用，在URL后追加/details可正常显示详情页
• 在应用目录下创建spin.toml文件：

  spin_manifest_version = 2
  
  [application]
  name = "server"
  version = "0.1.0"
  authors = ["you <you@you.com>"]
  description = "static server for flutter web app"
  
  [[trigger.http]]
  route = "/..."
  component = "server"
  
  [component.server]
  source = { url = "https://github.com/fermyon/spin-fileserver/releases/download/v0.2.1/spin_static_fs.wasm", digest = "sha256:5f05b15f0f7cd353d390bc5ebffec7fe25c6a6d7a05b9366c86dcb1a346e9f0f" }
  files = [{ source = "build/web", destination = "/" }]
  

• 执行spin up启动服务，访问带/details的URL时显示Not Found

问题原因 #

Flutter Web使用客户端路由时，/details这类路径并没有对应的物理文件，而是由前端代码解析路由并渲染页面。但Spin默认的静态文件服务器会尝试查找对应路径的文件，找不到就返回404，不会将请求转发给index.html处理。

解决方法 #

修改spin.toml，为静态组件添加fallback配置，将所有404请求重定向到/index.html，让Flutter的客户端路由接管处理。

修改后的spin.toml如下：

spin_manifest_version = 2

[application]
name = "server"
version = "0.1.0"
authors = ["you <you@you.com>"]
description = "static server for flutter web app"

[[trigger.http]]
route = "/..."
component = "server"

[component.server]
source = { url = "https://github.com/fermyon/spin-fileserver/releases/download/v0.2.1/spin_static_fs.wasm", digest = "sha256:5f05b15f0f7cd353d390bc5ebffec7fe25c6a6d7a05b9366c86dcb1a346e9f0f" }
files = [{ source = "build/web", destination = "/" }]
# 配置fallback，将所有未匹配的请求转发到index.html
[component.server.config]
fallback = "/index.html"

验证步骤 #

1. 执行flutter build web重新编译Flutter Web应用
2. 运行spin up启动服务
3. 直接访问/details路径，此时会加载index.html并由GoRouter正确解析路由，显示详情页

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