Flutter Web+Go Router部署Docker(Nginx)非根路径404问题

问题现象 #

开发环境中使用GoRouter可正常运行：从根路径/启动Web应用，或刷新/abc/def?var这类路径均无异常。但通过flutter build web构建应用并部署到Docker容器的Nginx后，访问非根路径会出现404错误。

原因分析 #

Flutter Web属于单页应用（SPA），所有路由逻辑由前端GoRouter处理，而非服务器端。Nginx默认会尝试在服务器文件系统中查找对应路径的物理文件，当访问非根路径（如/me、/blog/123/test）时，服务器上不存在这些路径的文件，因此返回404。

修复方案 #

调整Nginx配置，确保所有路由请求都转发到index.html由前端处理，同时保证静态资源正常加载。

调整后的Nginx配置 #

修改nginx.conf，补充MIME类型配置并优化路由转发规则：

user nginx;
worker_processes auto;
pid /run/nginx.pid;

include /etc/nginx/mime.types;
default_type application/octet-stream;

http {
    server {
        listen 80;
        root /usr/share/nginx/html;
        index index.html;

        # 静态资源直接返回，设置缓存策略
        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
            expires 1y;
            add_header Cache-Control "public, immutable";
        }

        # 所有非静态资源请求转发到index.html，由前端路由处理
        location / {
            try_files $uri $uri/ /index.html;
        }
    }
}

关键修改点 #

• 添加include /etc/nginx/mime.types;：确保Nginx正确识别静态资源的MIME类型，避免资源加载异常。
• 新增静态资源匹配规则：对JS、CSS、图片等文件直接返回，提升缓存效率。
• 保留try_files规则：当请求路径无对应物理文件时，自动转发到index.html，交由GoRouter处理前端路由。

验证步骤 #

1. 重新构建Docker镜像：

docker build -t flutter-web-app .

2. 启动容器：

docker run -p 8080:80 flutter-web-app

3. 访问非根路径（如http://localhost:8080/me、http://localhost:8080/blog/123/test）并刷新，确认不再出现404错误。

额外说明 #

• 你的GoRouter配置本身无问题，initialLocation: '/me'会在应用启动时自动跳转，开发环境中Flutter自带的Web服务器已默认处理SPA路由转发，但Nginx需要手动配置该规则。
• 若部署在子路径下（如https://example.com/app/），需在构建时添加flutter build web --base-href /app/参数，并将Nginx的location配置改为/app/。

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