将 DeckCraft 部署到 Web:静态站点构建、服务器头配置与 iframe 嵌入式集成指南
将 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 直接打包
构建与校验步骤
脚本的行为可按行拆解,顺序很重要:
- 除非传入
--skip-build,否则先执行(cd "$ROOT/apps/deckcraft-web" && trunk build --release),把发布构建输出写入dist/web(该目录由Trunk.toml的dist = "../../dist/web"指定)。 - 检查
dist/web/index.html是否存在;若使用--skip-build而此前从未构建过,则会提示先去掉该参数。 - 校验 URL 必须为相对路径:脚本用
grep -Eq '(src|href)="/[^/]'扫描index.html,一旦发现根绝对 URL 就报错退出,原因是站点必须以任意前缀提供服务。这条校验正是public_url = "./"的守护者。 - 在
$CARGO_TARGET_DIR/web-package下建立deckcraft-web-$VERSION目录,复制dist/web的全部内容。 - 追加示例服务器配置:
_headers、.htaccess,并把 README 以HOSTING.md的名字放进包内,让拿到 zip 的人无需回仓库即可看到托管说明。 - 调用
copy_docs复制项目根目录中存在的README.md、LICENSE、LICENSE-MIT、LICENSE-APACHE、COPYRIGHT、NOTICE,以及(构建时若设置了CRAFT_FONTS_DIR)字体许可证OFL-<family>.txt。该函数定义在 packaging/common.sh。 - 用
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…</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-ancestorsCSP。这是嵌入失败最常见的原因,且报错往往出现在浏览器控制台而非应用界面。
渲染器选择与 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 构建相对桌面版的行为差异,这些差异直接影响托管与嵌入的预期:
- 没有 TCP 控制通道——浏览器无法监听 socket。桌面版的自动化控制协议在 Web 构建中不存在。
- 文件 → 打开、插入 → 图片/音频/视频使用浏览器文件选择器,字节通过
Services::inbox异步返回,并应用到“发起选择时”的文档、幻灯片与操作上;取消选择器或文档已关闭时,文件被丢弃。 - 保存与导出触发浏览器下载。
- 拖放文件由
web::WebShell异步读取后经 inbox 投递。 - 偏好设置不持久化。
第 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 |
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),并验证示例文稿/空白文稿的初始状态符合预期
继续阅读与相关路径
- 托管说明原文:packaging/web/README.md
- 构建打包脚本:packaging/web/package.sh 与共享逻辑 packaging/common.sh
- 示例头配置:packaging/web/_headers、packaging/web/.htaccess
- Web 应用入口与构建选项:apps/deckcraft-web/index.html、apps/deckcraft-web/Trunk.toml
- 浏览器外壳实现:apps/deckcraft-web/src/main.rs、apps/deckcraft-web/src/web.rs
- 宿主服务与异步文件协议:crates/ui-egui/src/services.rs、crates/ui-egui/src/app/files.rs
- 桌面端、CLI 与 Web 的整体分层:docs/architecture.md