Rust + WebAssembly 上线实战指南
1 构建产物与目录结构
dist/
├── index.html
├── style.css
├── app.js # JS/TS 打包结果，含 wasm-bindgen glue code
├── app_bg.wasm # Rust → wasm-bindgen 编译产物
└── assets/...
- Rust → Wasm：
wasm-pack build --target web --release - 打包：
vite build/webpack --mode production/turbo run build - 产物拷贝：
rsync/scp/ CD 消息推送到对象存储（S3、OSS、COS）。
2 HTTP 服务器配置要点
2.1 设置正确的 MIME Type
| 服务器 | 配置片段 |
|---|---|
| NGINX | nginx\nhttp {\n types {\n application/wasm wasm;\n }\n}\n |
| Apache | apache\nAddType application/wasm .wasm\n |
| Cloudflare Pages / Netlify | 默认已支持；如需自定义，使用 _headers 或 headers 配置文件 |
原因：WebAssembly.instantiateStreaming(response) 只有在 Content-Type: application/wasm 时才能边下边编译。
2.2 启用压缩与缓存
-
Brotli/Gzip：
.wasm压缩比高达 ~70%，NGINX 例子：gzip on; gzip_types application/wasm; -
强缓存：
location /app_bg.wasm {add_header Cache-Control "public, max-age=31536000, immutable"; }打包工具默认生成带内容哈希文件名即可放心使用强缓存。
3 Streaming + 并行编译
现代浏览器对 wasm 文件执行 并行下载/编译，但需满足：
instantiateStreaming()API（Vite/Webpack ≥5 会自动生成）。- 正确 MIME。
- 不使用旧版
--no-modulesglue code。
实测 5 MB wasm 模块可在 200 ms 内完成编译（M1 Pro + Chrome 128）。
4 Webpack / Vite 生产优化 Checklist
| 项目 | 说明 | 工具链实现 |
|---|---|---|
| 代码分割 | wasm ↔ JS 拆分，首次只加载首屏逻辑 | import() 动态加载 / route-level code splitting |
| Tree-Shaking | 丢弃未用 JS glue | 默认开启，确保 mode=production |
INLINE_RUNTIME_CHUNK | 避免额外网络请求 | Vite build.inlineDynamicImports=true |
| SourceMap | 生产环境关闭或上传到 Sentry | devtool: false or hidden-source-map |
5 CDN & 边缘部署
-
对象存储 + CDN：S3 (+ CloudFront) / OSS (+ 阿里 CDN)。
-
完整性校验 (SRI)：
<script src="/app.js"integrity="sha384-…"crossorigin="anonymous"></script> -
HTTP/3 + 0-RTT：进一步降低首包延迟。
6 CI/CD 流水线示例（GitHub Actions）
name: deployon:push:branches: [main]jobs:build-and-upload:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v4- uses: dtolnay/rust-toolchain@stable- run: rustup target add wasm32-unknown-unknown- run: wasm-pack build --target web --release- run: npm ci && npm run build # Vite/Webpack 打包- uses: aws-actions/configure-aws-credentials@v4with: … # 省略鉴权配置- run: aws s3 sync dist/ s3://my-bucket --delete- run: aws cloudfront create-invalidation --distribution-id … --paths "/*"
7 生产安全要点
| Header | 作用 | 建议值 |
|---|---|---|
Content-Security-Policy | 限制资源来源 | default-src 'self'; script-src 'self'; |
X-Content-Type-Options | 防止 MIME 嗅探 | nosniff |
Cross-Origin-Embedder-Policy + Cross-Origin-Opener-Policy | 若使用 Wasm 线程 | require-corp + same-origin |
Strict-Transport-Security | 强制 HTTPS | max-age=31536000; includeSubDomains; preload |
8 常见问题（FAQ）
| 问题 | 解决方案 |
|---|---|
.wasm 返回 404？ | 路径大小写、CDN 缓存、MIME 漏配 |
instantiateStreaming 抛 TypeError？ | 检查 Content-Type；若后端改不了，用 fetch + arrayBuffer 退化加载 |
wasm 线程报错 SharedArrayBuffer unavailable？ | 设置 COOP+COEP，或降级单线程 |
| iOS 15 以下加载失败？ | 旧 WebKit 不完整支持 Wasm；提示用户升级或提供 JS Polyfill |
🚀 小结
- 构建：
wasm-pack+ 现代打包器；输出带哈希文件名。 - 服务器：
application/wasmMIME、压缩、长效缓存。 - Streaming：保持 ESM 导入或
instantiateStreaming，让编译与网络并行。 - CI/CD：交叉编译 + 单元测试 + 自动上传 + CDN 刷新。
- 安全：SRI、TLS、各类安全响应头到位。
遵循以上步骤，即可让 Rust + WebAssembly 应用在生产环境 快速、稳定、可维护 地运行。祝部署顺利！