完整引擎塞进网页:PhotoCraft WebAssembly 部署的分步操作

原创2026-10-11 17:14:242,321 阅读
文章标签:图像处理桌面应用跨平台

完整引擎塞进网页:PhotoCraft WebAssembly 部署的分步操作

PhotoCraft 是一个用纯 Rust 从零(clean-room)重实现 Adobe Photoshop 的开源项目,它有一个在其他图像编辑器身上很难见到的能力:整个引擎与完整 UI 被编译成了 WebAssembly,打开一个网页就能跑。没有 Electron、没有 webview 壳、没有一行手写 JavaScript——桌面端是 egui/eframe + wgpu 的原生应用,网页端是同一份 Rust 编译成 wasm,两者共享同一个 PhotocraftApp。

这意味着部署 PhotoCraft 到浏览器,本质上是把一份 Rust 工程改造成"能出静态产物、能在任意 CDN 上存活"的工程。本文基于仓库真实源码,拆解三件事:L0–L6 分层架构为何天生适配 wasm、trunk 构建与静态部署配置怎么写、打开网页即用的 PSD 工作流如何在浏览器里落地。

L0–L6 分层架构:为什么天生适配 wasm

PhotoCraft 的整个工作区按依赖方向划分成严格的层,规则表在 Crates and dependency layers:

层 Crate 职责
L0 geom、cms、color、raster 几何、ICC、颜色/混合数学、像素格式、写时复制瓦片
L0 standalone psd、codecs PSD/PSB 与扁平栅格格式解析/编码
L1 doc 纯数据文档模型
L2 ops、paint、algo、text、vector 历史操作、绘画、算法、文字、路径、形状
L3 compose、gpu、format CPU 合成、wgpu 合成、.pcraft 持久化
L4 io 文档模型与外部格式之间的导入导出
L5 engine Session、命令注册表、校验、历史集成
L6 ui-egui、automation egui 外壳、headless 自动化、MCP

这条分层规则被写成了代码而非文档承诺:xtask/src/layers.rs 里的规则引擎会解析 cargo metadata,检查"上层不得依赖下层以外的 crate""UI 工具包(egui/eframe/winit/rfd)只允许出现在 L6 及以上"等不变量,cargo xtask layers 是仓库的 CI 门禁之一。

分层对 wasm 的意义在于把"浏览器约束"挡在了架构底部:

  • 文件系统、TCP、原生窗口等浏览器不存在的设施,全部被隔离在 apps/photocraft-web 的 shell 层,通过 Services trait 注入。核心的 L0–L5 是纯算法与数据,天然无平台依赖;
  • L6 的 ui-egui 对引擎来说是"薄壳"(overview 原文:a thin shell over engine commands),引擎通过命令注册表暴露能力,UI 只是它的一个客户端。这意味着桌面 UI、CLI、JSON 控制通道、MCP 服务器和网页 UI 走的是同一条 command registry 路径,网页版不是"缩水移植",而是同一个 Session;
  • AGENTS.md 把"Never break wasm"列为仓库不变量第 7 条:L0–L6 必须能通过 cargo check --target wasm32-unknown-unknown,文件系统代码必须用 cfg(not(target_arch = "wasm32")) 包起来或走平台服务。cargo xtask wasm 是日常开发与 CI 都会跑的门禁。

docs/architecture.md 在项目原则里直接写明了目标:"The core compiles to wasm32, which keeps a browser demo possible."——网页版不是事后补的 demo,而是从一开始就参与架构决策的编译目标。

wasm 构建:trunk + wasm-bindgen + 一个为体积调优的 profile

依赖与入口

apps/photocraft-web/Cargo.toml 是工作区里唯一一个把 eframe(带 wgpu 与 accesskit 特性)、wasm-bindgen、rfd(异步文件选择器)、web-sys 等浏览器栈拉进来的应用 crate,同时它声明了 heif feature——可选地打开 HEIC/HEIF 解码(官方构建通过 --features heif 打开)。它依赖的是工作区同层的 photocraft-engine、photocraft-io、photocraft-codecs、photocraft-doc、photocraft-ui-egui——也就是"整个引擎"。

入口文件 apps/photocraft-web/src/main.rs 的注释写得很直白:

Runs the same photocraft_ui_egui::PhotocraftApp as the desktop app through eframe's web runner (wgpu: WebGPU where available, WebGL2 otherwise).

#[cfg(target_arch = "wasm32")] 分支才进入 web::start(),原生编译时则打印提示拒绝运行——这个二进制只属于浏览器。

构建配置链

构建由 apps/photocraft-web/index.html 顶部的 trunk 指令驱动:

<link data-trunk rel="rust" data-bin="photocraft-web"
      data-cargo-profile="wasm-release" data-cargo-features="heif"
      data-wasm-opt="z" data-weak-refs />

data-cargo-profile="wasm-release" 指向工作区根 Cargo.toml 里为浏览器专门调优的 profile:

[profile.wasm-release]
inherits = "release"
opt-level = "s"        # 整体按体积优化
lto = "fat"
codegen-units = 1
strip = "debuginfo"

[profile.wasm-release.package.photocraft-raster]
opt-level = 3
# ...color / cms / compose / algo / paint 同样保留 opt-level 3

注释里记录了这个 profile 的来历:wasm 每次访问都要重新下载,而 Cloudflare Pages/Workers 对单文件有 25 MiB 上限,所以面向体积优化——fat LTO + opt-level "s",但像素处理相关的六个 crate(raster、color、cms、compose、algo、paint)保留 opt-level 3,保证滤镜和合成在浏览器里依然快。仓库记录这把这个 profile 从 release 的 26.3 MiB 压到了 18.8 MiB。

data-wasm-opt="z" 让 trunk 再跑一轮 wasm-opt -Oz 做二次瘦身。实测尺寸(记录在 packaging/web/README.md):18.8 MiB 原始、gzip 后 7.8 MiB、Brotli 后 5.6 MiB。

构建与本地预览三步走:

rustup target add wasm32-unknown-unknown
cargo install trunk --locked
cd apps/photocraft-web
trunk build --release     # 输出到 ../../dist/web(index.html + .js 胶水 + .wasm)
trunk serve --release     # 本地开发服务器 http://127.0.0.1:8765

trunk serve 的端口、绑定地址与输出目录由 apps/photocraft-web/Trunk.toml 定义:dist = "../../dist/web"、public_url = "./"、filehash = true。

体积门禁是发布的一部分

packaging/web/package.sh 把部署做成了流水线:trunk build --release → 检查产物里没有根绝对路径 URL(保证站点能部署在任何前缀路径下)→ 检查每个 .wasm 不超过 24 MiB(Cloudflare 的硬上限是 25 MiB,脚本留了 1 MiB 余量,实测仓库里 0.2.x 之前发过 25.8 MiB 的 wasm 被 Cloudflare 拒收,issue #198 之后加了这道闸)→ 打成 photocraft-web-<version>.zip,附上 _headers、.htaccess 与托管说明。

静态部署:一份"从任何路径都能跑"的站点

网页版没有任何服务端代码,产物就是一个纯静态目录。关键在三个配置点。

相对路径 + 内容哈希

Trunk.toml 的 public_url = "./" 让所有资源走相对路径,所以同一份产物既能在 https://example.com/ 根路径跑,也能挂在 https://example.com/tools/photocraft/ 前缀下或 CDN bucket 里。filehash = true 给 .wasm/.js 文件名带上内容哈希,于是它们可以被永久缓存,只有 index.html 需要重新校验。

MIME、压缩与缓存头

packaging/web/_headers 给出了 Netlify / Cloudflare Pages 的标准头规则:

/*.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

其中 Content-Type: application/wasm 是硬要求——浏览器在错误的 MIME 下会拒绝流式编译,导致加载变慢或干脆失败。压缩同样重要:gzip/Brotli 能把下载量从约 19 MiB 压到 8 MiB / 5.6 MiB。仓库给 nginx 的参考配置在 packaging/web/README.md:

location /photocraft/ {
    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"; }
}

一个常被忽略的细节:PhotoCraft 的渲染依赖 WebGPU,而 WebGPU(和剪贴板)只在安全上下文里工作——https:// 或 http://localhost。部署在纯 HTTP 域名下时浏览器会自动回退到 WebGL2;两个都没有才会在画布位置给出错误提示。另外它不用 SharedArrayBuffer,所以不需要 COEP/COOP 隔离头,这让它在各种托管平台上几乎零摩擦。

iframe 嵌入

由于资源全部相对化,站点天然可以嵌进任意页面:

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

沙箱化的 iframe 至少需要 allow-scripts allow-same-origin allow-downloads allow-popups——没有 allow-same-origin 就没有 localStorage(偏好设置会每次回到默认值),没有 allow-downloads 则保存/导出(浏览器下载)会被拦截。

打开网页即用的 PSD 工作流

部署只是外壳,真正的价值在 apps/photocraft-web/src/web.rs 里那套浏览器版 Services 实现——它把桌面的文件语义逐一映射到浏览器原语上。

打开:异步文件选择器 + inbox 队列

桌面版 File → Open 是同步读盘,浏览器做不到。网页版用 rfd::AsyncFileDialog 弹出选择器,字节通过 wasm_bindgen_futures::spawn_local 异步读回,推进 Services::inbox(一个 Arc<Mutex<Vec<(String, Vec<u8>)>>>),应用每帧从 inbox 里取数据。支持的后缀名单(OPEN_EXTS)直接覆盖了桌面版的能力面:pcraft、psd、psb、psdt、PNG/JPEG/TIFF/WebP/EXR/HDR 等栅格格式,还有 DNG/CR2/CR3/NEF/ARW 等相机 RAW,以及 .abr 笔刷和 .grd 渐变预设。拖放文件则由 WebShell 在应用看到之前截获 dropped_files,用 DroppedFile::bytes_async 异步读完再喂进同一个 inbox。

导入导出:同一套 io 管线

导入与导出直接复用桌面版的编解码管线,而不是网页端另写一套:

import: Some(Box::new(|name: &str, bytes: &[u8]| {
    photocraft_io::import(name, bytes).map(|r| (r.document, r.warnings)).map_err(|e| e.to_string())
})),

photocraft-io 会按魔法字节或扩展名路由到 photocraft-psd(PSD/PSB)、photocraft-codecs(栅格格式)或 photocraft-format(.pcraft)。导出同样走 photocraft_io::export,可配置 JPEG 质量、WebP 无损、TIFF 图层、XMP 嵌入。保存没有对话框——建议文件名直接变成下载文件名,字节用 Blob + object URL + 临时 <a download> 触发浏览器下载(下载实现 里的 download(),所有步骤都由 Rust 完成,并给不同扩展名映射了正确的 MIME)。

渲染:WebGPU → WebGL2 → CPU 三级回退

桌面版用 wgpu 做 GPU 合成(photocraft-gpu),网页版沿用同一渲染路径:eframe 的 web runner 优先 WebGPU,没有则自动回退 WebGL2。URL 查询参数可以强制切换:

参数 效果
(无) WebGPU 可用则用,否则 WebGL2
?webgl 强制 WebGL2(WebGPU 驱动异常时排查用)
?cpu 强制 CPU 画布路径(最慢、兼容性最好)

web.rs 里甚至把 W3C Pointer Events 的压感、倾斜、旋转和橡皮擦位(buttons 第 5 位)接进了应用的 stylus 输入流,浏览器里的数位笔体验和桌面一致。

取舍:浏览器边界与诚实记录

网页版并非零差异,仓库注释与文档如实记录了边界:

  • 没有 TCP 控制服务器(浏览器不能监听 socket),自动化靠 headless Chrome 的 DevTools 协议;
  • 没有崩溃恢复与自动保存(web 构建没有 autosave services);
  • 不内嵌 craft-fonts:实测在 wasm 里多放一套 UI 字体就会把体积从 24.19 MB 顶到 28.87 MB、撞破 24 MiB 门禁,因此网页版暂未携带日文字体,后续方案是运行时在 wasm 旁加载;
  • 偏好设置存放在浏览器 localStorage(键 photocraft.preferences),跨域 iframe 下可能因第三方存储分区而被遗忘。

这些取舍全部由"体积门禁 + 平台能力"驱动,且每一项都在源码注释或 docs/development.md 的 Web build 一节有明确记录——对一个把"诚实评估"写进路线图的项目来说,这是部署文档该有的样子。

PhotoCraft 网页版工作界面:编辑神奈川冲浪里,展示完整图层与调整面板

结语:把"部署网页版"当作一等架构目标

PhotoCraft 的网页部署之所以干净,不是因为最后补了一层 wasm 包装,而是因为架构从一开始就把 wasm 当成了编译目标之一:L0–L6 严格分层、Never break wasm 成为仓库不变量、文件系统代码被隔离到 Services 注入点、像素热路径按体积 profile 单独调优、发布脚本对产物尺寸设闸。当这些约束都提前内化进工程纪律,剩下的部署步骤就只是一份静态目录、三行头规则和一段 nginx 配置——而用户得到的,是打开浏览器就能编辑 PSD 的完整引擎。

登录后查看全文
photocraft