Flutter Web部署报错：Uncaught (in promise) Error: Minified React error #321

Minified React错误#321对应的原始问题是React无法渲染null或undefined的元素，在Flutter Web场景下，这个报错通常不是真的React代码问题，而是部署环节的配置、资源加载或渲染模式兼容问题导致Flutter框架初始化异常触发的底层错误。以下是针对性的解决方法：

1. 修正资源基础路径 #

如果你的应用部署在服务器的子路径下（比如https://xxx.com/my-app/），构建时未指定base href会导致资源加载失败：

• 重新构建时添加--base-href参数：

  flutter build web --base-href "/my-app/"
  

• 或者手动修改build/web/index.html里的<base href="/">，替换为你的实际部署路径，比如<base href="/my-app/">

2. 确认构建产物完整上传 #

检查服务器上的web目录是否和本地build/web的文件完全一致：

• 重点确认assets文件夹、main.dart.js、flutter.js、canvaskit/（如果用canvaskit渲染器）这些核心文件是否存在，大小是否和本地匹配
• 避免上传时遗漏或部分文件损坏

3. 切换渲染模式 #

Flutter Web默认的auto渲染模式可能在某些服务器环境下出现兼容性问题，尝试强制使用canvaskit渲染器：

• 构建命令改为：

  flutter build web --web-renderer canvaskit
  

• 或者直接修改index.html中的Flutter初始化代码，添加渲染器指定：

  _flutter.loader.loadEntrypoint({
    serviceWorker: {
      serviceWorkerVersion: serviceWorkerVersion,
    },
    renderer: "canvaskit"
  });
  

4. 配置服务器MIME类型 #

部分服务器没有正确识别Flutter Web的特殊文件类型，导致浏览器无法解析：

• Nginx用户在配置文件中添加：

  location ~ \.dart\.js$ {
    add_header Content-Type application/javascript;
  }
  location ~ \.wasm$ {
    add_header Content-Type application/wasm;
  }
  

• Apache用户在.htaccess中添加：

  AddType application/javascript .dart.js
  AddType application/wasm .wasm
  

5. 适配前端路由（如果使用自定义路由） #

如果应用用了Flutter路由，部署到非根目录时服务器需要配置支持前端路由，避免刷新页面返回404：

• Nginx配置示例（假设部署路径是/my-app/）：

  location /my-app/ {
    try_files $uri $uri/ /my-app/index.html;
  }
  

• Apache配置示例（.htaccess）：

  RewriteEngine On
  RewriteBase /my-app/
  RewriteRule ^index\.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /my-app/index.html [L]
  

内容的提问来源于stack exchange，提问作者Muhammad Saqib Aziz