如何把LocalStudio.dev部署为静态站点:必备路由、GitHub Pages与S3托管完整指南

原创2026-11-13 12:50:101,927 阅读

如何把LocalStudio.dev部署为静态站点:必备路由、GitHub Pages与S3托管完整指南

LocalStudio.dev 是一个纯浏览器端的 Canva 风格演示文稿工作台,内置本地 Web AI 能力。它没有任何产品后端,整个应用都是静态文件——这意味着你可以用一条 npm run build 命令,把它部署到 GitHub Pages、S3 兼容对象存储或任意静态托管服务。本文带你走通本地构建静态站点、配置 5 条必备路由,并完成 GitHub Pages 与 S3 两种托管方式的完整流程。

LocalStudio.dev 浏览器端演示文稿编辑器静态站点

为什么 LocalStudio 可以零后端静态部署?

很多带 AI 功能的应用都依赖服务端 API,但 LocalStudio 把 AI 和项目存储全部留在了浏览器一侧:

  • Web AI:优先使用 Chrome 内置 AI API(Prompt API、Translator API 等),也可用 WebGPU 加载 Hugging Face 模型,权重缓存在浏览器中;
  • 项目持久化:通过浏览器本地文件夹 API 把项目 JSON、素材、版本历史保存在你自己的磁盘上;
  • S3 镜像(可选):项目可以同步到 S3 兼容存储用于公开分享,凭证也只保存在当前浏览器配置文件里。

官方托管文档 hosting.md 明确说明:Hosting does not move AI or project storage to a backend——托管方只负责分发静态文件。

第一步:本地构建静态站点产物

克隆仓库并安装依赖:

git clone https://gitcode.com/gh_mirrors/lo/localstudio
cd localstudio
npm ci

然后执行生产构建:

npm run build

这条命令会依次构建 4 个子应用,最后运行 prepare-pages-artifacts.mjs 脚本补齐 WebMCP 入口。构建完成后,所有可部署的产物集中在根目录的 dist/ 下:

构建产物 来源 说明
dist/ apps/landing 产品落地页,站点根路由 /
dist/editor/ apps/editor Web AI 幻灯片编辑器 /editor/
dist/joystick/ apps/joystick 演示者遥控器 PWA /joystick/
dist/docs/ apps/docs VitePress 文档站 /docs/
dist/webmcp/index.html 由脚本从编辑器入口复制 WebMCP 展示页 /webmcp/

LocalStudio 静态编辑器:提示词生成幻灯片的工作界面

5 条必备路由与 SPA 回退

根据官方 hosting.md 文档,静态主机必须支持以下 5 条路由:

  • /
  • /editor/
  • /joystick/
  • /webmcp/
  • /docs/

关键点:在这些路由前缀下,无扩展名的深层链接必须回退到对应应用的入口文件(如 /editor/projects/xxx 要返回 dist/editor/index.html)。这是典型的前端单页应用路由,各应用的 base path 统一由 app-routes.js 定义,并在各 vite.config.ts 中通过 LOCALSTUDIO_BASE_PATH 环境变量支持自定义前缀。

💡 如果你把站点挂在子路径下(例如 https://yourname.dev/studio/),构建前设置 LOCALSTUDIO_BASE_PATH=/studio/ 即可,joystick 应用另有 LOCALSTUDIO_JOYSTICK_BASE_PATH 变量(默认 /joystick/)。

第二步:GitHub Pages 最短部署路径

GitHub Pages 是零成本方案,官方落地页的 CNAME 文件正是为绑定 localstudio.dev 自定义域名准备的。

1. 构建产物提交到 gh-pages 分支

npm run build

将 dist/ 目录内容推送到一个发布分支(如 gh-pages),并在仓库的 Pages 设置中指向该分支。

2. 配置 SPA 回退(关键步骤)

Pages 默认对找不到文件的路径返回 404。最简单的办法是放一个 404.html,内容为重定向到首页:

<meta http-equiv="refresh" content="0;url=/" />

并配合 <base href="/"> 标签让编辑器内部路由正常工作。文档站 /docs/ 由 VitePress 生成,配置在 config.ts 中启用了 cleanUrls,深层链接同样依赖回退规则。

3. 利用项目自带的缓存头配置

apps/landing/public/_headers 文件已经给出了生产级缓存策略示例:/assets/* 与静态图片、视频使用 Cache-Control: public, max-age=31536000, immutable。如果你用的是 Cloudflare Pages,这个 _headers 文件可以直接复制过去使用;GitHub Pages 则可通过自定义域名 + Cloudflare 代理生效。

LocalStudio 演示者模式:桌面端放映加手机 PWA 遥控

第三步:S3 兼容对象存储托管方案

需要更高可用性或全球 CDN 加速时,可以把 dist/ 上传到任意 S3 兼容服务:AWS S3、Cloudflare R2、自建 MinIO 均可。

  1. 开启静态网站托管:创建 Bucket 后上传 dist/ 全部内容,静态网站索引设为 index.html;
  2. 配置 SPA 回退规则:S3 的 Redirect Rules 中把 404 状态码的 key 前缀重定向到对应入口(editor/* → editor/index.html,根路径 → index.html),与官方 5 条路由一一对应;
  3. 绑定域名与 HTTPS:关联自定义域名并配置证书,R2 可直挂 CDN 无请求费;
  4. 开启不可变缓存:复制 _headers 中的策略,为 *.webp、*.png、*.mp4 等设置一年期的 immutable 缓存。

⚠️ 注意区分两个概念:这里说的 S3 是托管静态文件的存储;而 LocalStudio 产品内置的 "S3-compatible projects" 是用户项目的数据镜像功能(配合 docker-compose.minio.yml 本地启动 MinIO 即可体验),两者互不冲突,数据始终留在浏览器端。

LocalStudio S3 兼容项目镜像设置面板与对象浏览器

部署后哪些能力仍然可用?

静态部署不损失任何核心功能——这正是 LocalStudio 的 local-first 设计哲学:

  • ✅ Web AI 生成幻灯片、图片生成、图像编辑(需 Chrome + WebGPU 环境)
  • ✅ 本地文件夹保存项目与版本历史
  • ✅ 演示者模式与 /joystick/ 遥控器 PWA
  • ✅ /webmcp/ 展示页的浏览器 Agent 工具发现

WebMCP 展示页 的 15 个工具全部由同源的编辑器静态资源驱动:

LocalStudio WebMCP 展示页:Agent 与用户操作同一个编辑器

唯一的例外是需要独立信令服务的演示者远程控制(LOCALSTUDIO_PEERJS_* 环境变量注入),生产环境可配合 e2e-peer-server.mjs 部署一个小型信令端点。

常见部署陷阱清单

症状 原因与解决
刷新 /editor/xxx 后 404 缺少 SPA 回退,配置 404 → 入口 index.html 重定向
子路径部署后资源 404 构建时漏设 LOCALSTUDIO_BASE_PATH
/webmcp/ 白屏 跳过了 prepare-pages-artifacts.mjs,dist/webmcp/index.html 不存在
文档链接失效 VitePress cleanUrls 要求 /docs/ 前缀同样配置回退
素材加载慢 未按 _headers 策略开启长缓存

相关模块与文件速查

按以上流程走一遍,你就拥有了一个和 localstudio.dev 同构的私有静态站点:5 条路由全通、AI 全在本地、项目数据只属于你的浏览器。

登录后查看全文
localstudio