docs: 添加 Flutter Web 部署指南

- 解决 WebAssembly 加载错误 - 提供完整的部署步骤 - 包含常见问题解决方案
2026-03-25 09:32:44 +08:00
parent a54de87618
commit fe6d71dfca
1 changed files with 160 additions and 0 deletions
--- a/DEPLOY_GUIDE.md
+++ b/DEPLOY_GUIDE.md
@@ -0,0 +1,160 @@
+# Flutter Web 部署指南
+
+## 问题：WebAssembly 加载错误
+
+错误信息：
+```
+TypeError: Failed to execute 'compile' on 'WebAssembly':
+An argument must be provided, which must be a Response or Promise<Response> object
+```
+
+## 原因分析
+
+1. **文件不完整** - canvaskit.wasm 或其他 WASM 文件未正确部署
+2. **MIME 类型错误** - 服务器未正确返回 `.wasm` 文件的 MIME 类型
+3. **缓存问题** - 浏览器缓存了旧版本的文件
+
+## 部署步骤
+
+### 方式1: 使用部署脚本（推荐）
+
+```bash
+# 1. SSH 登录服务器
+ssh root@8.155.172.147
+
+# 2. 进入项目目录
+cd /www/wwwroot/monisuo
+
+# 3. 拉取最新代码
+git pull
+
+# 4. 执行部署脚本
+./deploy_flutter_web.sh
+```
+
+### 方式2: 手动部署
+
+```bash
+# 1. 进入项目目录
+cd /www/wwwroot/monisuo
+
+# 2. 拉取最新代码
+git pull
+
+# 3. 清理旧文件
+rm -rf /www/wwwroot/monisuo-h5/*
+
+# 4. 复制新构建文件
+cp -r flutter_monisuo/build/web/* /www/wwwroot/monisuo-h5/
+
+# 5. 设置权限
+chown -R www:www /www/wwwroot/monisuo-h5
+chmod -R 755 /www/wwwroot/monisuo-h5
+
+# 6. 检查文件
+ls -lh /www/wwwroot/monisuo-h5/main.dart.js
+ls -lh /www/wwwroot/monisuo-h5/canvaskit/canvaskit.wasm
+```
+
+## 配置 Nginx WASM MIME 类型
+
+检查并添加 WASM MIME 类型：
+
+```bash
+# 编辑 Nginx MIME 类型配置
+vim /www/server/nginx/conf/mime.types
+
+# 确保包含以下内容：
+application/wasm  wasm;
+
+# 重启 Nginx
+nginx -t
+nginx -s reload
+```
+
+## 验证部署
+
+### 1. 检查文件完整性
+
+```bash
+# 检查关键文件
+ls -lh /www/wwwroot/monisuo-h5/main.dart.js
+ls -lh /www/wwwroot/monisuo-h5/canvaskit/canvaskit.wasm
+ls -lh /www/wwwroot/monisuo-h5/flutter.js
+ls -lh /www/wwwroot/monisuo-h5/index.html
+
+# 检查 WASM 文件数量
+find /www/wwwroot/monisuo-h5 -name "*.wasm" | wc -l
+# 应该输出: 4 或更多
+```
+
+### 2. 检查 MIME 类型
+
+```bash
+# 测试 WASM 文件的 MIME 类型
+curl -I http://8.155.172.147:8061/canvaskit/canvaskit.wasm
+
+# 应该看到:
+# Content-Type: application/wasm
+```
+
+### 3. 清除浏览器缓存
+
+- Chrome: `Ctrl + Shift + Delete` (Windows) 或 `Cmd + Shift + Delete` (Mac)
+- 选择 "缓存的图片和文件"
+- 点击 "清除数据"
+
+## 常见问题
+
+### 问题1: 仍然加载失败
+
+**解决方案：**
+```bash
+# 强制刷新 Nginx 缓存
+nginx -s reload
+
+# 检查 Nginx 错误日志
+tail -f /www/server/nginx/logs/error.log
+```
+
+### 问题2: MIME 类型不正确
+
+**解决方案：**
+```nginx
+# 在 Nginx 站点配置中添加
+location ~* \.wasm$ {
+    types {
+        application/wasm wasm;
+    }
+    add_header Content-Type application/wasm;
+}
+```
+
+### 问题3: 文件权限问题
+
+**解决方案：**
+```bash
+# 修复权限
+chown -R www:www /www/wwwroot/monisuo-h5
+chmod -R 755 /www/wwwroot/monisuo-h5
+```
+
+## 部署检查清单
+
+- [ ] 代码已拉取到最新版本
+- [ ] main.dart.js 文件存在且完整（约 3.2MB）
+- [ ] canvaskit/canvaskit.wasm 文件存在（约 6.8MB）
+- [ ] 所有 WASM 文件都已复制（4个或更多）
+- [ ] 文件权限正确（755）
+- [ ] 文件所有者正确（www:www）
+- [ ] Nginx 已配置 WASM MIME 类型
+- [ ] Nginx 已重启
+- [ ] 浏览器缓存已清除
+- [ ] 页面可以正常访问
+
+## 联系支持
+
+如果问题仍然存在，请检查：
+1. Nginx 错误日志：`/www/server/nginx/logs/error.log`
+2. 浏览器控制台的详细错误信息
+3. 网络请求是否正常（Chrome DevTools → Network 标签）