Rust + WebAssembly 上线实战指南

1 构建产物与目录结构

text 复制代码

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 例子：
nginx 复制代码
```
gzip on;
gzip_types application/wasm;
```
强缓存：
nginx 复制代码
```
location /app_bg.wasm {
    add_header Cache-Control "public, max-age=31536000, immutable";
}
```
打包工具默认生成带内容哈希文件名即可放心使用强缓存。

3 Streaming + 并行编译

现代浏览器对 wasm 文件执行 并行下载/编译，但需满足：

instantiateStreaming() API（Vite/Webpack ≥5 会自动生成）。
正确 MIME。
不使用旧版 --no-modules glue 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)：

html 复制代码

<script src="/app.js"
        integrity="sha384-..."
        crossorigin="anonymous"></script>

HTTP/3 + 0-RTT：进一步降低首包延迟。

6 CI/CD 流水线示例（GitHub Actions）

yaml 复制代码

name: deploy

on:
  push:
    branches: [main]

jobs:
  build-and-upload:
    runs-on: ubuntu-latest
    steps:
      - 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@v4
        with: ...                             # 省略鉴权配置
      - 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/wasm MIME、压缩、长效缓存。
Streaming ：保持 ESM 导入或 instantiateStreaming，让编译与网络并行。
CI/CD：交叉编译 + 单元测试 + 自动上传 + CDN 刷新。
安全：SRI、TLS、各类安全响应头到位。

遵循以上步骤，即可让 Rust + WebAssembly 应用在生产环境 快速、稳定、可维护 地运行。祝部署顺利！