Flutter Web WASM Docker部署后显示空白页问题求助

一、空白页问题修复 #

使用flutter build web --release --wasm构建后出现空白页，核心原因是Nginx未正确配置WASM的MIME类型，同时缺少Flutter单页应用的路由重写规则。

1. 创建自定义Nginx配置文件 #

在项目根目录新建nginx.conf文件，添加WASM MIME类型和路由规则：

events {}

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

    # 配置WASM对应的MIME类型，否则浏览器无法正确解析
    types {
        application/wasm wasm;
    }

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

        # Flutter单页应用路由重写，解决刷新页面404、路由跳转失效问题
        location / {
            try_files $uri $uri/ /index.html;
        }
    }
}

2. 更新Dockerfile引入配置 #

在运行阶段的Nginx镜像中，替换默认配置为自定义文件：

# Stage 2 - 创建运行镜像
FROM nginx:1.25.3-alpine
COPY --from=build-env /app/build/web /usr/share/nginx/html
# 替换默认Nginx配置
COPY nginx.conf /etc/nginx/nginx.conf

二、Dockerfile全面优化 #

原Dockerfile存在构建效率低、镜像体积大的问题，优化后版本如下：

优化后的完整Dockerfile #

# Stage 1 - 构建环境：使用官方Flutter镜像，无需手动搭建环境
FROM flutter:3.16.0-stable AS build-env

# 分层复制依赖文件，利用Docker缓存，仅当依赖变动时重新下载
COPY pubspec.yaml pubspec.lock ./
RUN flutter pub get

# 复制项目代码
COPY . .
# 构建WASM版本的Web应用
RUN flutter build web --release --wasm

# Stage 2 - 运行环境：轻量Nginx Alpine镜像
FROM nginx:1.25.3-alpine
# 复制构建产物
COPY --from=build-env /app/build/web /usr/share/nginx/html
# 复制自定义Nginx配置
COPY nginx.conf /etc/nginx/nginx.conf

优化点说明 #

• 使用官方Flutter镜像：避免手动安装依赖、克隆Flutter仓库，构建速度更快，环境更稳定。
• 分层COPY策略：先复制依赖配置文件执行flutter pub get，后续代码改动时可复用依赖缓存，减少重复构建时间。
• 指定镜像版本：放弃latest标签，使用具体版本号，保证构建环境一致性。
• 轻量运行镜像：采用Nginx Alpine版本，镜像体积大幅缩小，运行资源占用更低。

三、验证步骤 #

1. 确保项目根目录存在nginx.conf文件。
2. 重新构建镜像：

docker build -t customer-portal .

3. 启动容器：

docker run -d -p 8080:80 customer-portal

4. 访问http://localhost:8080，打开浏览器开发者工具（F12），检查flutter.wasm是否成功加载，控制台是否有报错。

若仍存在问题，可进入容器验证文件是否存在：

# 进入容器终端
docker exec -it <容器ID> sh
# 检查WASM文件是否存在
ls /usr/share/nginx/html/flutter.wasm

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