如何把LocalStudio.dev部署为静态站点:必备路由、GitHub Pages与S3托管完整指南
如何把LocalStudio.dev部署为静态站点:必备路由、GitHub Pages与S3托管完整指南
LocalStudio.dev 是一个纯浏览器端的 Canva 风格演示文稿工作台,内置本地 Web AI 能力。它没有任何产品后端,整个应用都是静态文件——这意味着你可以用一条 npm run build 命令,把它部署到 GitHub Pages、S3 兼容对象存储或任意静态托管服务。本文带你走通本地构建静态站点、配置 5 条必备路由,并完成 GitHub Pages 与 S3 两种托管方式的完整流程。
为什么 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/ |
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 代理生效。
第三步:S3 兼容对象存储托管方案
需要更高可用性或全球 CDN 加速时,可以把 dist/ 上传到任意 S3 兼容服务:AWS S3、Cloudflare R2、自建 MinIO 均可。
- 开启静态网站托管:创建 Bucket 后上传
dist/全部内容,静态网站索引设为index.html; - 配置 SPA 回退规则:S3 的 Redirect Rules 中把
404状态码的 key 前缀重定向到对应入口(editor/*→editor/index.html,根路径 →index.html),与官方 5 条路由一一对应; - 绑定域名与 HTTPS:关联自定义域名并配置证书,R2 可直挂 CDN 无请求费;
- 开启不可变缓存:复制 _headers 中的策略,为
*.webp、*.png、*.mp4等设置一年期的immutable缓存。
⚠️ 注意区分两个概念:这里说的 S3 是托管静态文件的存储;而 LocalStudio 产品内置的 "S3-compatible projects" 是用户项目的数据镜像功能(配合 docker-compose.minio.yml 本地启动 MinIO 即可体验),两者互不冲突,数据始终留在浏览器端。
部署后哪些能力仍然可用?
静态部署不损失任何核心功能——这正是 LocalStudio 的 local-first 设计哲学:
- ✅ Web AI 生成幻灯片、图片生成、图像编辑(需 Chrome + WebGPU 环境)
- ✅ 本地文件夹保存项目与版本历史
- ✅ 演示者模式与
/joystick/遥控器 PWA - ✅
/webmcp/展示页的浏览器 Agent 工具发现
WebMCP 展示页 的 15 个工具全部由同源的编辑器静态资源驱动:
唯一的例外是需要独立信令服务的演示者远程控制(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 策略开启长缓存 |
相关模块与文件速查
- 官方托管说明:hosting.md
- 路由常量定义:app-routes.js
- WebMCP 入口生成脚本:prepare-pages-artifacts.mjs
- 编辑器构建配置:vite.config.ts
- 演示者 PWA 构建配置:vite.config.ts
- 缓存头参考:_headers
- 自定义域名文件:CNAME
按以上流程走一遍,你就拥有了一个和 localstudio.dev 同构的私有静态站点:5 条路由全通、AI 全在本地、项目数据只属于你的浏览器。




