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

当 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：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）比浏览器控制台更可靠——后者常仅反映资源加载失败的表面现象。

最后补充一点：部署后，每次向 GitHub 主分支推送代码，Vercel 都会自动触发重建（前提是在 Vercel 控制台开启 Git Integration）。从此告别 sanity deploy 报错，无需再为“missing context value”反复重装依赖。

实际上，用 Vercel 托管 Sanity Studio 不仅解决了崩溃问题，还能获得 HTTPS 全站加密、全球 CDN 加速、灰度发布及实时日志等企业级能力——这正是现代内容协作平台应有的基础设施底座。