Rust + WebAssembly 生产部署指南

1 · 最小可行部署（MVP）

前端打包

wasm-pack build --target web --release      # 生成 .wasm + JS 包装器  
npm run build / vite build / webpack …       # 打包 HTML/CSS/JS 资源

拷贝产物 到生产服务器的站点目录

dist/
├── index.html
├── pkg/
│   ├── my_app_bg.wasm
│   └── my_app.js
└── assets/…

配置 HTTP 服务器（Nginx / Apache / …）确保：
- 正确的 Content‑Type: application/wasm
- gzip / brotli 压缩（Wasm 可再减 ~‑50 %）
- 长效缓存（ETag 或 immutable hash 文件名）

2 · 为什么必须设置 `application/wasm`？

浏览器的 WebAssembly.instantiateStreaming 会在网络下载的同时编译 Wasm —— 前提是服务器返回头部 Content‑Type: application/wasm。
否则它会回退到 fetch + ArrayBuffer，不仅额外一次内存拷贝，还失去编译/下载流水线带来的启动提速。

3 · Nginx 示例

http {include       mime.types;types {application/wasm wasm;   # <‑‑ 新增}gzip            on;          # 建议同时开启 brotligzip_types      application/wasm;server {listen 80;root /var/www/my_site/dist;location / {try_files $uri $uri/ =404;}# 高优缓存策略（可选）location ~* \.wasm$ {add_header Cache-Control "public, max-age=31536000, immutable";}}
}

4 · Apache 示例（两种方式）

4.1 修改全局 `/etc/mime.types`

application/wasm   wasm

然后 sudo systemctl restart apache2。

4.2 站点级 `.htaccess`

<FilesMatch "\.wasm$">AddType application/wasm .wasm# 强缓存Header set Cache-Control "max-age=31536000, public, immutable"
</FilesMatch>

5 · 加速技巧

技巧	作用	备注
Brotli 压缩 (`br`)	Wasm 的压缩比通常优于 Gzip	Nginx 1.19+、Apache mod_brotli
HTTP/2 + TLS	并发下载 + 头部压缩	大文件仍推荐 `link rel=preload`
Service Worker 缓存	离线运行、秒开启	尤其适合 PWA 场景
CDN 边缘节点	降延迟、自动缓存	记得在源站同样设置正确 MIME

6 · 持续集成到持续部署（CI/CD）

name: build‑and‑deploy
on:push:branches: [ main ]jobs:build:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v4- uses: actions-rs/toolchain@v1with:toolchain: stabletarget: wasm32-unknown-unknown- run: wasm-pack build --release --target web- run: npm ci && npm run build- uses: actions/upload-artifact@v4with: { name: dist, path: dist }deploy:needs: buildruns-on: ubuntu-latestenvironment: productionsteps:- uses: actions/download-artifact@v4with: { name: dist, path: ./dist }# 示例：推送到 Nginx 服务器- run: rsync -avz ./dist/ user@server:/var/www/my_site/

cargo check --target wasm32-unknown-unknown 放在 build 阶段，确保每次 PR 都维持可编译状态。
完整端到端测试可用 wasm-pack test --node 或 --headless 结合 Puppeteer/Cypress。

7 · 常见“跑不动”排查清单

浏览器控制台报 “MIME type incorrect”
→ 确认服务器确实返回 Content-Type: application/wasm。
跨域 CORS 错误
→ .wasm 与 .js 静态资源同源最省事；否则设置 Access‑Control‑Allow‑Origin。
文件路径 404
→ 构建工具（Vite/Webpack/Rollup）别忘了 publicPath 或 base 选项。
Worker/Service Worker 加载失败
→ Worker 脚本也需要正确 MIME (text/javascript)；Wasm 可用 instantiateStreaming 内嵌或预加载。