PhotoCraft 网页版：自托管 WebAssembly 构建

PhotoCraft 网页版（WASM）是什么、如何把 photocraft-web.zip 部署到任意静态服务器或 Docker、浏览器要求（WebGPU 或 WebGL2），以及与桌面版的功能差异。

非官方社区指南更新于 2026 年 10 月 10 日

最新版本 v0.5.0 · 2026 年 10 月 8 日所有文件均直接从官方 GitHub Release 下载。

Self-hosted web buildphotocraft-web-0.5.0.zipWASM8.9 MB

PhotoCraft 的整个引擎和界面都可以编译成 WebAssembly。每个版本都会发布 photocraft-web-<版本>.zip，它是一个纯静态网站，放到任何 Web 服务器上就能用，不需要后端。图片在访问者自己的设备上打开和处理，服务器端不存储任何文档。上方表格链接的是 GitHub 官方发布页上的压缩包。不想自己部署的话，可以直接在本站的在线编辑器里试用网页版。网页版和桌面版一样，仍处于早期 alpha 阶段。

压缩包里有什么

解压后是一个 photocraft-web-<版本>/ 文件夹：

文件	说明
`index.html`	页面本身，所有资源都用相对路径加载
`photocraft-web-<hash>.js`	wasm-bindgen 生成的胶水代码（ES 模块）
`photocraft-web-<hash>_bg.wasm`	应用主体
`_headers`、`.htaccess`	适用于 Netlify / Cloudflare Pages 和 Apache 的示例响应头配置

v0.6.0 的 .wasm 为 25,145,515 字节（略低于 24 MiB），整个压缩包为 11,094,419 字节（约 10.6 MiB）。官方给出的压缩数据只有 0.2.x 版本的：当时 .wasm 原始大小约 19 MiB，gzip 后约 8 MiB，Brotli 后约 5.6 MiB。发布脚本会在 .wasm 超过 24 MiB 时直接报错，保证不超过 Cloudflare Pages / Workers 单文件 25 MiB 的上限。

四步自托管

下载发布页上的 photocraft-web-<版本>.zip 和 SHA256SUMS.txt，先校验：

sha256sum -c --ignore-missing SHA256SUMS.txt     # Linux
shasum -a 256 photocraft-web-0.6.0.zip           # macOS，与 SHA256SUMS.txt 对照

解压并在本地试运行：
```
unzip photocraft-web-0.6.0.zip
cd photocraft-web-0.6.0
python3 -m http.server 8765
```
打开 http://localhost:8765/ 即可。localhost 属于安全上下文，WebGPU 可以正常启用。
上传文件夹里的内容到任意静态托管：nginx、Apache、Caddy、挂在 CDN 后面的对象存储、Netlify 或 Cloudflare Pages 都行。因为全部是相对路径，放在域名根目录（https://example.com/）或子路径（https://example.com/tools/photocraft/）下都能用，不需要重新构建。
验证： 打开页面，打开一张图片，再保存或导出一次。

需要注意的服务器设置

MIME 类型： .wasm 必须以 application/wasm 返回，.js 用 text/javascript。类型不对时浏览器无法流式编译 wasm，加载会很慢甚至失败。nginx 请确认 mime.types 里有 application/wasm wasm;。
压缩： 为 .wasm、.js 和 .html 开启 gzip 或 Brotli。以 0.2.x 版本为例，.wasm 的下载量可从约 19 MiB 降到约 8 MiB（gzip）或 5.6 MiB（Brotli）。
缓存： .wasm 和 .js 的文件名带内容哈希，可以设置 Cache-Control: public, max-age=31536000, immutable；index.html 设置 no-cache，保证用户能拿到新版本。
HTTPS： WebGPU 和剪贴板只在安全上下文（https:// 或 http://localhost）中可用。在其他地址用纯 HTTP 访问时，会退回 WebGL2。
不需要跨域隔离头： PhotoCraft 不使用 SharedArrayBuffer，无需 COOP/COEP。如果你的站点已经发送 COEP require-corp，记得给应用文件加上 Cross-Origin-Resource-Policy。

官方托管指南中的 nginx 示例：

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"; }
}

用 Netlify、Cloudflare Pages 或 Apache 的话，压缩包自带的 _headers 和 .htaccess 已经包含了同样的设置。

用 Docker 部署

仓库里有一个 Dockerfile，从源码构建网页版并用 nginx 在 8080 端口提供服务。官方注明这套配置由社区维护：CI 不构建它，正式发布也不使用它，因此可能落后于官方 zip。在克隆下来的仓库根目录运行：

docker build --load -t photocraft-web:local .
docker run -d --name photocraft-web --restart unless-stopped \
  -p 8080:8080 photocraft-web:local

然后访问 http://localhost:8080/。首次构建需要几分钟。公网部署时请在前面加 HTTPS 反向代理；代理和容器在同一台机器上时，只绑定本机回环地址（-p 127.0.0.1:8080:8080）。构建参数和子路径部署方法见官方托管指南。

嵌入到其他页面

PhotoCraft 会自动填满所在的 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 加了 sandbox，至少需要 allow-scripts allow-same-origin allow-downloads allow-popups；缺少 allow-downloads 时保存和导出会被拦截。托管 PhotoCraft 的站点不要发送 X-Frame-Options: DENY。

浏览器要求

浏览器需要支持 WebGPU 或 WebGL2。PhotoCraft 用 wgpu 渲染，有 WebGPU 就用 WebGPU，否则自动退回 WebGL2；两者都不支持的浏览器只会看到一条提示。可以在网址后加参数手动指定：

网址参数	效果
（无）	优先 WebGPU，否则 WebGL2
`?webgl`	强制 WebGL2，WebGPU 驱动有问题时使用
`?cpu`	强制 CPU 画布（最慢，但兼容性最好）

网页版与桌面版的区别

	网页版	桌面版
打开文件	浏览器文件选择器	系统对话框、拖放、文件关联
保存	保存和导出都会触发下载	直接写入磁盘
自动保存与崩溃恢复	没有，请勤保存。v0.6.0 起，有未保存的内容时，关闭或刷新页面前会先询问（#1424）	有
首选项	存在浏览器 `localStorage` 中（跨站 iframe 里可能丢失）	设置文件夹
数位笔压感与倾斜	支持（Pointer Events）	目前仅 Windows（#79）
中文、日文、韩文界面	暂不可用：这些文字会显示成空白方框（#1615），请使用英文界面	可用，正式版还内嵌了日文界面字体
CLI、MCP 服务、`--control` 控制通道	不可用	可用

网页版适合先体验 PhotoCraft，或者在团队内部提供一个免安装的编辑器。日常使用时，Windows、macOS 或 Linux 桌面版额外提供崩溃恢复、本地文件访问、命令行工具和完整的中文界面。网页版（包括本站的在线编辑器）目前只能使用英文界面，详见界面语言设置。页面一直空白时可以参考故障排除。

在本站使用，或自行部署

photocraft.im 是非官方的社区指南。本站的在线编辑器运行的是未经修改的官方网页版，文件由本站自己的存储提供。该页面写明了当前运行的版本，以及它所用官方压缩包的 SHA-256，你可以拿它和官方 SHA256SUMS.txt 核对。

如果要自行部署，仍请从官方 storytold/photocraft GitHub 发布页下载网页版压缩包，并按上面第 1 步用 SHA256SUMS.txt 校验。

对来路不明的第三方“PhotoCraft 在线版”要保持警惕。在里面打开私人图片之前，先确认几件事：它有没有写明运行的版本、给出能和官方发布页对照的校验值；是否原样提供官方构建、没有改动；编辑器里有没有被加进广告或跟踪脚本。这些都无从确认的话，你就无法知道它运行的是哪个版本、有没有被改动过。

本页目录

压缩包里有什么
四步自托管
需要注意的服务器设置
用 Docker 部署
嵌入到其他页面
浏览器要求
网页版与桌面版的区别
在本站使用，或自行部署

相关指南