Sticker Forge 部署终极指南：GitHub Pages 静态导出与 Cloudflare Workers 双路径详解

Sticker Forge 是一款开源的 WebGL 贴纸制作工具，可以把文字或上传图片变成能"撕拉"的 3D 贴纸——拖动真实的模切边缘，贴纸会卷起并露出缎面背面，还带有深度感知阴影与撕拉音效。想要把它部署上线分享给更多人？项目原生提供了两条零折腾的Sticker Forge 部署路径：面向零服务器场景的GitHub Pages 静态导出，以及支持 D1 数据库与图片优化的Cloudflare Workers 全功能部署。本文带你快速走通这两条路径。

部署前准备：环境要求与获取代码 🛠️

两条路径共享同一套本地环境要求，先完成一次性准备：

• Node.js ≥ 22.13.0（package.json 中的engines字段明确了版本下限）
• npm（依赖安装与脚本执行）

获取代码并安装依赖：

git clone https://gitcode.com/gh_mirrors/st/sticker-forge.git cd sticker-forge npm install

所有部署相关的脚本都集中在 package.json 中，先记住这几个"主力选手"：

路径一：GitHub Pages 静态导出部署 📄

一键构建静态站点：GITHUB_PAGES 开关原理

静态导出的核心开关在 next.config.ts 中：当环境变量GITHUB_PAGES=true时，Next.js 的output切换为"export"并开启trailingSlash，构建产物变成一组纯静态 HTML/JS/CSS 文件。

本地构建与线上完全一致的静态产物只需一条命令：

npm run build:pages

构建成功后会生成out/目录，里面就是可以直接放到任何静态托管上的完整站点。

💡两个针对静态托管的细节（同样由GITHUB_PAGES=true触发）：

• Webpack 注入module: falsefallback，并加载 build/inline-audio-loader.cjs 音频内联 loader；
• 撕拉音效经过裁剪、转单声道和高通处理后，直接内联进 JS 包，无需单独托管音频文件——原始录音保留在 lib/assets/ 中。

自动上线：推送 main 分支即触发部署

项目内置了 GitHub Actions 工作流 .github/workflows/deploy-pages.yml，流程非常直白：

1. 触发条件：推送到main分支，或手动执行workflow_dispatch；
2. build 任务：检出代码 → 安装 Node 22.13.0 →npm ci→npm run build:pages→ 将out/目录上传为 Pages 工件；
3. deploy 任务：通过actions/deploy-pages@v4发布到 GitHub Pages 环境；
4. 内置concurrency控制，新推送会自动取消进行中的旧部署。

也就是说：只要仓库 Settings 中开启 Pages，日常开发推代码即部署，不需要任何额外配置。

路径二：Cloudflare Workers 全功能部署 ⚡

本地开发：一条命令拉起完整 Workers 环境

npm run dev

该命令通过 vite.config.ts 中的vinext+@cloudflare/vite-plugin组合启动：

• Worker 入口为 worker/index.ts，由 Miniflare 在本地模拟ASSETS、DB、IMAGES等 Cloudflare 绑定；
• 本地 D1 绑定使用占位database_id（见 vite.config.ts 的localBindingConfig），生产环境由控制面注入真实值；
• 类型声明见 cloudflare-env.d.ts，Env.DB即 D1 数据库句柄。

构建与生产启动：三步完整构建

npm run build # 依次执行 typecheck → build:lib → vinext build npm run start # 本地验证生产产物

npm run build是三步流水线（package.json）：

其中 embed 库由 vite.lib.config.ts 配置，特意把three打进产物，使用者无需安装任何依赖，复制即用。

可选能力：D1 数据库与图片优化

Workers 路径独有的两个超能力：

• D1 数据库：通过 Drizzle ORM 接入，迁移配置见 drizzle.config.ts；默认表结构为空（db/schema.ts），examples/d1/ 提供了一个完整的notes增删查改示例，照抄即可拥有自己的数据层；
• 图片优化：Worker 中/_vinext/image路由（worker/index.ts）借助IMAGES绑定按请求宽度/格式实时转换图片，且带安全头；.svg默认直接透传不做优化。

两条部署路径怎么选？🤔

新手建议：先跑npm run build:pages+ GitHub Pages 体验零服务器部署；等需要持久化数据时再切换到 Workers 路径，代码完全不用改，只是换一套构建命令。

常见问题 🙋

Q1：为什么静态版本没有音频文件也能播放撕拉声？音频在构建期被内联进 JS 包（见 next.config.ts 的 webpack 规则），public/里自然看不到单独的音频请求。

Q2：部署后想把这个贴纸嵌入自己的博客/网站？直接使用public/embed/sticker-forge.es.js注册的<sticker-forge>Web Component，参考 examples/embed.html 的独立页面示例即可，两条部署路径产出的站点都自带该文件。

Q3：npm run dev报 Node 版本错误？升级到 Node 22.13.0 或更高版本——这是两条部署路径共同的硬性要求。

到这里，你已经掌握了 Sticker Forge 从本地构建到 GitHub Pages 自动上线、再到 Cloudflare Workers 全功能部署的完整链路。选一条路径，npm install之后几分钟内就能拥有属于自己的贴纸工坊 ✨。