Sanity Studio 迁移部署指南：从本地崩溃到 Vercel 一键上线

作者：袖梨 2026-06-18

当 Sanity Studio 因 Schema 更新后出现“Workspace: missing context value”等运行时错误，且本地恢复无效时，核心解法是放弃旧式 sanity deploy（已停用），改用现代前端云平台（如 Vercel）构建并托管 Studio 前端。

当 sanity studio 因 schema 更新后出现“workspace: missing context value”等运行时错误，且本地恢复无效时，核心解法是放弃旧式 `sanity deploy`（已停用），改用现代前端云平台（如 vercel）构建并托管 studio 前端。

Sanity 自 2023 年起已正式弃用内置的 sanity deploy 命令，不再提供免费的官方托管服务。你遇到的 "Workspace: missing context value" 错误，表面是 React Context 初始化失败，实则多由以下原因触发：

构建产物（dist/）未正确生成或包含损坏的依赖；
本地 sanity start 启动的是开发服务器，而生产环境需完整静态构建；
@sanity/vision 或 sanity 主包版本不兼容（尤其在 v3.15.x 系列中，对 React 18 的 Context API 有严格要求）。

✅ 正确路径：使用 Vercel 托管构建后的 Studio 前端，完全绕过本地部署陷阱。

✅ 三步完成迁移部署（含验证）

1. 构建生产级 Studio 包

确保项目根目录下执行：

# 清理旧构建（避免缓存污染）rm -rf dist# 使用 Sanity CLI 构建静态资源（输出至 dist/）sanity build# 验证构建结果ls -la dist/# 应看到 index.html、assets/、static/ 等标准静态结构

⚠️ 注意：sanity build 本质是打包一个纯静态 React 应用，不依赖 Node.js 运行时——这正是 Vercel 完美支持的场景。

2. 全局安装并登录 Vercel CLI

# 推荐使用 npm（兼容性更稳）npm install -g vercel# 验证安装vercel --version  # 应输出 vercel/x.y.z# 登录账户（支持 GitHub / Email / GitLab）vercel login

首次登录会自动打开浏览器完成 OAuth 认证，并将凭证保存至本地配置。

3. 一键部署与持续集成

# 在项目根目录（含 dist/ 目录）执行vercel --prod# 首次部署将引导你：#   • 选择项目名称（默认为文件夹名，可回车确认）#   • 设置框架（Vercel 自动识别为 Static Site）#   • 指定静态文件路径（输入 `dist`，而非 `.`）#   • 是否链接 Git 仓库（推荐选 `y`，启用 push-to-deploy）

部署成功后，终端将输出类似：

https://your-project-name.vercel.app [copied to clipboard]

访问该 URL，即可看到正常运行的 Sanity Studio —— 此时所有 Schema 修改、Vision 插件、Desk 工具均能稳定加载。

? 关键注意事项

不要直接部署源码目录：Vercel 默认部署 .，但 Sanity Studio 必须部署 dist/ 目录。若跳过手动指定，可在 vercel.json 中显式配置：
```
{  "builds": [{ "src": "dist/**", "use": "@vercel/static" }],  "routes": [{ "src": "/(.*)", "dest": "/index.html" }]}
```
环境变量安全：若 Studio 使用了自定义 API 或密钥（如 SANITY_STUDIO_PROJECT_ID），请在 Vercel 项目后台 → Settings → Environment Variables 中添加，切勿硬编码在代码中。
版本锁定建议：在 package.json 中将 sanity 和 @sanity/vision 锁定为精确版本（如 "sanity": "3.15.1"），避免 CI/CD 中因 minor 版本升级引入不兼容变更。
本地调试替代方案：开发阶段仍可用 sanity dev；生产问题排查时，优先检查 Vercel 构建日志（Build Logs），而非浏览器控制台报错——后者常为资源加载失败的表象。