将 DeckCraft 部署到 Web:静态站点构建、服务器头配置与 iframe 嵌入式集成指南

原创2026-11-01 12:08:531,737 阅读

将 DeckCraft 部署到 Web:静态站点构建、服务器头配置与 iframe 嵌入式集成指南

DeckCraft 的浏览器版本是一个完全静态的 WebAssembly 站点:源码编译后,产物只有一个 index.html、一份 hashed JS 胶水代码和一个 .wasm 应用体,没有服务端逻辑,因此可以放在任意静态托管、对象存储或 CDN 上。本文以 packaging/web/README.md 为主线,逐条讲解产物结构、构建脚本、必需服务器设置、iframe 嵌入方式与渲染器回退标志,并对照 apps/deckcraft-web 的 Rust 源码说明这些配置背后的真实行为,帮助你判断“为什么这样配才不踩坑”。

产物结构:一个自包含的静态目录

deckcraft-web-<version>.zip 来自 GitHub Release,或者由 packaging/web/package.sh 自行构建。解压后是 deckcraft-web-<version>/ 目录,内容如下:

文件 作用
index.html 页面本身,所有资源都通过相对 URL 加载
deckcraft-web-<hash>.js wasm-bindgen 生成的胶水代码(ES module)
deckcraft-web-<hash>_bg.wasm 应用本体,体积由 packaging/web/package.sh 打印
_headers、.htaccess 面向 Netlify/Cloudflare Pages 与 Apache 的示例响应头规则

除上述文件外,打包脚本还会额外放入若干文档与许可证文件(见下文“构建流程”)。由于没有任何服务端代码,只要目标环境能提供静态文件服务,就可以直接上传该目录的全部内容。

关键点在于:<hash> 是内容哈希。这来自 apps/deckcraft-web/Trunk.toml 中的 filehash = true,意味着文件名会随内容变化,因而可以放心地设置长缓存。

构建流程:trunk、wasm32 目标与 package.sh

环境依赖

packaging/web/package.sh 的头部注释写明了两个前提:

  • trunk:brew install trunk 或 cargo install trunk --locked;缺失时脚本会直接报错退出
  • wasm32-unknown-unknown 编译目标

脚本用法:

packaging/web/package.sh              # 完整构建并打包
packaging/web/package.sh --skip-build # 复用已有的 dist/web 直接打包

构建与校验步骤

脚本的行为可按行拆解,顺序很重要:

  1. 除非传入 --skip-build,否则先执行 (cd "$ROOT/apps/deckcraft-web" && trunk build --release),把发布构建输出写入 dist/web(该目录由 Trunk.toml 的 dist = "../../dist/web" 指定)。
  2. 检查 dist/web/index.html 是否存在;若使用 --skip-build 而此前从未构建过,则会提示先去掉该参数。
  3. 校验 URL 必须为相对路径:脚本用 grep -Eq '(src|href)="/[^/]' 扫描 index.html,一旦发现根绝对 URL 就报错退出,原因是站点必须以任意前缀提供服务。这条校验正是 public_url = "./" 的守护者。
  4. 在 $CARGO_TARGET_DIR/web-package 下建立 deckcraft-web-$VERSION 目录,复制 dist/web 的全部内容。
  5. 追加示例服务器配置:_headers、.htaccess,并把 README 以 HOSTING.md 的名字放进包内,让拿到 zip 的人无需回仓库即可看到托管说明。
  6. 调用 copy_docs 复制项目根目录中存在的 README.md、LICENSE、LICENSE-MIT、LICENSE-APACHE、COPYRIGHT、NOTICE,以及(构建时若设置了 CRAFT_FONTS_DIR)字体许可证 OFL-<family>.txt。该函数定义在 packaging/common.sh。
  7. 用 zip -qr9 打包,最后 ls -lh 打印 zip 体积。

版本号不是硬编码的:common.sh 中的 workspace_version() 用 awk 读取根 Cargo.toml 的 [workspace.package] version,可通过环境变量 DECKCRAFT_VERSION 覆盖;产物目录默认落在 $DIST(dist/release)。因此你会看到 dist/release/deckcraft-web-<version>.zip 这样的路径。

注意:trunk build --release 需要在 apps/deckcraft-web 目录内执行,直接在仓库根目录运行会找不到 index.html 入口。

页面入口与构建选项

apps/deckcraft-web/index.html 是 trunk 的构建目标。它只有一块画布和一个加载占位:

<canvas id="deckcraft_canvas"></canvas>
<div id="deckcraft_loading">Loading DeckCraft&hellip;</div>

以及 trunk 指令行:

<link data-trunk rel="rust" data-bin="deckcraft-web" data-wasm-opt="z" data-weak-refs />

其中 data-wasm-opt="z" 指示使用 wasm-opt -Oz 做体积优化,data-weak-refs 则允许 wasm-bindgen 使用弱引用以改善内存回收。页面样式把画布设为绝对定位铺满视口、overflow: hidden,这是“应用填满容器”的前提,也解释了后文 iframe 中“调整 iframe 尺寸而不是应用本身”的建议。

任意路径部署:相对 URL 与缓存粒度

README 明确要求:所有 URL 都是相对的(public_url = "./" 在 apps/deckcraft-web/Trunk.toml),因此同一个包可以同时工作在:

  • 域名根:https://example.com/
  • 子路径:https://example.com/tools/deckcraft/
  • CDN 桶:直接从存储桶域名提供服务

由于资源名带内容哈希,它们可以被永久缓存;只有 index.html 需要重新校验。这条组合正好解决了“发版后用户仍拿到旧 wasm”的常见问题:index.html 不缓存,所以每次都会引用新的哈希文件名。

如果你的构建产物被改写(例如某些部署平台自动重写资源路径为绝对路径),package.sh 的 grep 校验会在打包阶段就把它拦住,而不是等上线后才在子路径上报 404。

必需的服务器设置

README 把服务器配置归为五条硬性要求,逐条都对应着真实的浏览器行为。

1. MIME 类型:.wasm 必须是 application/wasm

浏览器拒绝以其他 MIME 类型对 wasm 做流式编译,结果是加载极慢或根本加载不了。.js 应为 text/javascript。多数托管平台已经正确配置;用 nginx 时检查 mime.types 中是否包含:

application/wasm wasm;

Apache 侧对应的示例写在 packaging/web/.htaccess:

AddType application/wasm .wasm
AddType text/javascript .js

2. 压缩:gzip 或 Brotli

对 .wasm、.js、.html 开启 gzip 或 Brotli,README 给出的经验值是下载体积约缩小 60%。也可以预压缩(例如 brotli -k *.wasm)后由服务器发送 Content-Encoding: br。使用预压缩时要注意:文件名保持不变,因此缓存头仍按原文件名设置。

.htaccess 中的 deflate 片段(需要 mod_deflate):

<IfModule mod_deflate.c>
  AddOutputFilterByType DEFLATE application/wasm text/javascript text/html
</IfModule>

3. 缓存:哈希文件长缓存,index.html 不缓存

目标头:

Cache-Control: public, max-age=31536000, immutable

作用于带哈希的 .wasm 与 .js;index.html 使用 no-cache。

packaging/web/_headers(Netlify / Cloudflare Pages 语法)完整地表达了这个策略:

/*
  X-Content-Type-Options: nosniff

/*.wasm
  Content-Type: application/wasm
  Cache-Control: public, max-age=31536000, immutable

/*.js
  Cache-Control: public, max-age=31536000, immutable

/index.html
  Cache-Control: no-cache

.htaccess 用 mod_headers 的 FilesMatch 实现同样效果(mod_mime 必需,mod_deflate 与 mod_headers 可选):

<IfModule mod_headers.c>
  <FilesMatch "\.(wasm|js)$">
    Header set Cache-Control "public, max-age=31536000, immutable"
  </FilesMatch>
  <FilesMatch "^index\.html$">
    Header set Cache-Control "no-cache"
  </FilesMatch>
</IfModule>

4. HTTPS:WebGPU 与剪贴板的硬门槛

WebGPU(以及剪贴板 API)只在安全上下文中可用,也就是 https:// 或 http://localhost。在其他位置的纯 HTTP 下,应用会退回到 WebGL2。换句话说,用局域网 IP 直接以 HTTP 访问,虽然能跑,但拿不到 WebGPU 路径。

5. 不需要特殊隔离头

DeckCraft 不使用 SharedArrayBuffer,因此不需要 Cross-Origin-Opener-Policy 或 Cross-Origin-Embedder-Policy。但如果你的站点本来就发送 COEP require-corp,就必须为应用文件补上 Cross-Origin-Resource-Policy: same-origin(文件在 CDN 上时用 cross-origin),否则资源会被拦下。这是一个典型的“宿主站点策略牵连静态应用”的场景。

完整 nginx 示例

README 给出的最小可用配置(把应用挂在 /deckcraft/ 前缀下):

location /deckcraft/ {
    types { application/wasm wasm; text/javascript js; text/html html; }
    gzip on;
    gzip_types application/wasm text/javascript text/html;
    location ~* \.(wasm|js)$ { add_header Cache-Control "public, max-age=31536000, immutable"; }
    location ~* index\.html$ { add_header Cache-Control "no-cache"; }
}

这里的嵌套 location 顺序用于让更精确的匹配覆盖外层 types 声明之外的缓存策略,配合上文 public_url = "./" 就能直接挂在子路径下工作。

本地验证

在解压目录内执行:

python3 -m http.server 8765

然后访问 http://localhost:8765/。localhost 属于安全上下文,因此本地就能获得 WebGPU;同时 python3 -m http.server 会按扩展名推断 .wasm 的 MIME 类型,适合做冒烟测试。若需更接近生产(压缩、哈希、自动重建),可以直接在 apps/deckcraft-web 里用 trunk serve——Trunk.toml 中的 [serve] 指定了 127.0.0.1:8768。

在页面中嵌入(iframe)

README 提供的嵌入片段:

<iframe
  src="https://example.com/deckcraft/"
  title="DeckCraft presentations"
  style="width: 100%; height: 720px; border: 0;"
  allow="fullscreen; clipboard-read; clipboard-write"
  allowfullscreen>
</iframe>

围绕这段代码有几条必须理解的约束:

  • 应用填满 iframe 并跟随其尺寸,所以要设置 iframe 的尺寸,而不是去改应用。这与 index.html 里 html, body { width: 100%; height: 100%; overflow: hidden } 及绝对定位画布的实现一致。
  • 键盘快捷键只有在用户点击进入 iframe 后才会进入应用,这与任何嵌入式应用的行为相同。
  • 跨域嵌入可用。Web 构建不跨访问保留偏好,每次都从示例演示文稿(或带 ?blank 时的空白文稿)开始。这一点在源码中得到确认:apps/deckcraft-web/src/web.rs 每次启动都新建 Session,非 blank 时调用 deckcraft_engine::sample::open_sample,否则执行 file.new。
  • 沙箱 iframe 至少需要 sandbox="allow-scripts allow-same-origin allow-downloads allow-popups"。缺少 allow-downloads 时,保存与导出(浏览器下载)会被拦截。
  • 不要发送 X-Frame-Options: DENY,也不要配置排除嵌入页面的 frame-ancestors CSP。这是嵌入失败最常见的原因,且报错往往出现在浏览器控制台而非应用界面。

渲染器选择与 URL 标志

DeckCraft 使用 wgpu 渲染:浏览器支持时用 WebGPU,否则自动退到 WebGL2。URL 查询参数可以覆盖这一行为,且对 iframe 的 src 同样有效:

标志 效果
(无) 有 WebGPU 就用 WebGPU,否则 WebGL2
?webgl 强制 WebGL2 后端(适用于 WebGPU 驱动异常时)
?blank 以空白演示文稿启动,而不是示例文稿
?show 立即进入幻灯片放映(适合 kiosk / 嵌入式演示)

例如:<iframe src="https://example.com/deckcraft/?webgl" ...>。

这些标志并非文档层面的约定,而是 apps/deckcraft-web/src/web.rs 中的实际分支逻辑:

let mut options = eframe::WebOptions::default();
if query().contains("webgl")
    && let eframe::egui_wgpu::WgpuSetup::CreateNew(create) = &mut options.wgpu_options.wgpu_setup
{
    create.instance_descriptor.backends = eframe::wgpu::Backends::GL;
}

也就是说 ?webgl 做的事情是把 wgpu 实例的后端集合收窄为 Backends::GL;不传该参数时沿用 eframe 默认设置,即 WebGPU 优先、WebGL2 回退。而 ?blank 与 ?show 分别在应用构建阶段决定“打开示例文稿还是新建空白文稿”和“是否调用 start_show(0, false)”。

启动日志里会打印实际使用的后端,便于排查:

log::info!("deckcraft-web {}: wgpu backend {:?}", env!("CARGO_PKG_VERSION"), rs.adapter.get_info().backend);

日志通过 eframe::WebLogger::init(log::LevelFilter::Info) 安装,在浏览器控制台可见。既没有 WebGPU 也没有 WebGL2 的浏览器会得到一条替代表述:启动失败时,脚本把加载占位元素的内容替换为错误说明,而成功时直接移除该占位元素。对应代码在 web.rs:

match result {
    Ok(()) => el.remove(),
    Err(e) => el.set_inner_html(&format!("<p>DeckCraft failed to start: {e:?}</p><p>A browser with WebGPU or WebGL2 is required.</p>")),
}

Web 版与桌面版的差异(源码视角)

apps/deckcraft-web/src/main.rs 的模块注释列出了 Web 构建相对桌面版的行为差异,这些差异直接影响托管与嵌入的预期:

  1. 没有 TCP 控制通道——浏览器无法监听 socket。桌面版的自动化控制协议在 Web 构建中不存在。
  2. 文件 → 打开、插入 → 图片/音频/视频使用浏览器文件选择器,字节通过 Services::inbox 异步返回,并应用到“发起选择时”的文档、幻灯片与操作上;取消选择器或文档已关闭时,文件被丢弃。
  3. 保存与导出触发浏览器下载。
  4. 拖放文件由 web::WebShell 异步读取后经 inbox 投递。
  5. 偏好设置不持久化。

第 2、4 条对应的异步协议定义在 crates/ui-egui/src/services.rs。宿主提供的 Services 中,Web 构建填充的是 open_async(接收 purpose 与请求 id)、write/download、以及 inbox;pick_open、pick_save、read 保持 None,所以 UI 自动走异步分支。InboxFile 携带 id、name、bytes,InboxEvent 有 File 与 Cancelled 两种:

pub enum InboxEvent {
    File(InboxFile),
    /// The picker was dismissed or the file could not be read. `id` will not be applied.
    Cancelled { id: u64 },
}

在 apps/deckcraft-web/src/web.rs 中,选择器按用途配置文件过滤:

purpose 过滤器 扩展名
picture Pictures png, jpg, jpeg, gif, webp, bmp, tif, tiff
audio Audio wav, mp3, m4a, aac, flac, ogg, opus, aif, aiff
video Video mp4, m4v, mov, webm
其他(打开文稿) Presentations deckcraft, pptx, potx, ppsx, txt, md

取消选择时会推送 InboxEvent::Cancelled { id: request };成功读取后推送携带 file.file_name() 与字节的 InboxEvent::File,两者都会 ctx.request_repaint() 唤醒 UI。

应用侧在 crates/ui-egui/src/app/files.rs 消费这些事件:drain_inbox 取走队列,Cancelled 仅把对应 id 从 pending_files 中移除,File 交给 apply_external_file;而请求身份在选择开始时通过 begin_external_file 记录,此时就把当前文档、目标位置与操作捕获下来。这解释了 README 中“文档关闭则文件被丢弃”的行为——目标已失效,apply_external_file 找不到对应 id 便直接返回。测试用例 crates/ui-egui/src/inbox_tests.rs 覆盖了取消与乱序投递等情形。

保存与导出的下载细节

Web 端下载在 download() 中实现:把字节包成 Blob、用 URL.createObjectURL 生成临时地址、创建一个隐藏的 <a download> 点击触发,随后移除元素并在 10 秒后 revokeObjectURL(点击已派发,下载持有自己的引用)。文件的 MIME 类型由扩展名映射:

扩展名 MIME
png image/png
jpg / jpeg image/jpeg
gif image/gif
pdf application/pdf
txt text/plain
pptx application/vnd.openxmlformats-officedocument.presentationml.presentation
deckcraft application/zip
其他 application/octet-stream

这条链路也解释了为什么沙箱 iframe 必须带 allow-downloads:只要下载被浏览器策略拦截,保存与导出就整体失效。

另外,桌面端的“打印”会导出 PDF 后交给系统打开,而 Web 端在 files.rs 中走 pick_save 为 None 的分支,直接把 PDF 作为下载交给用户。

部署检查清单

把上述内容压缩成上线前可逐项核对的清单:

  • [ ] 用 packaging/web/package.sh 生成 zip,确认包内存在 index.html、hashed .js、_bg.wasm、_headers、.htaccess、HOSTING.md 与许可证文件
  • [ ] 上传的是目录内容,站点可位于任意路径前缀(不要假设部署在域名根)
  • [ ] .wasm 返回 application/wasm,.js 返回 text/javascript
  • [ ] .wasm/.js/.html 开启 gzip 或 Brotli
  • [ ] hashed 资源 Cache-Control: public, max-age=31536000, immutable,index.html 为 no-cache
  • [ ] 通过 https:// 提供服务(或使用 localhost)以保留 WebGPU 与剪贴板能力
  • [ ] 未设置 Cross-Origin-Opener-Policy/COEP;若宿主站点已有 COEP,则补 Cross-Origin-Resource-Policy
  • [ ] 嵌入场景下未发送 X-Frame-Options: DENY 或排他的 frame-ancestors
  • [ ] 沙箱 iframe 至少授予 allow-scripts allow-same-origin allow-downloads allow-popups
  • [ ] 需要 kiosk 或纯空白起步时,正确使用 ?show、?blank、?webgl
  • [ ] 浏览器控制台确认后端日志(WebGPU 或 WebGL2),并验证示例文稿/空白文稿的初始状态符合预期

继续阅读与相关路径

登录后查看全文
deckcraft