如何在 VSCode 中配置运行并调试 Sanity.io 后台代码

在 VSCode 里折腾 Sanity.io 后台代码，遇到最多的坑，我反复踩过的有这么几个，今天一次性说清楚。

一、明明装了 Sanity，终端却提示 Command not found: sanity

这个提示，我刚开始遇到时也愣了一下。问题其实出在环境上：要么是全局没装 sanity-cli，要么是 VSCode 的终端压根没读取到系统 PATH。

先别急着重装。先做一件事：在你的系统终端（不是 VSCode 里面那个）里跑一下 which sanity 或者 sanity --version，看看能不能正常返回路径和版本号——这是排查的第一站。

• 如果系统终端里跑得通，但 VSCode 里报错，那说明 VSCode 启动时没加载你的 shell 配置文件（比如 ~/.zshrc 或 ~/.bash_profile）。这时候关掉所有 VSCode 窗口，直接在命令行里敲 code --new-window 启动——新窗口会继承当前 shell 的环境变量。
• 如果还是不行，那就走局部安装路线：在项目根目录 npm install --sa ve-dev @sanity/cli，然后全程用 npx 调用，比如 npx sanity start，绕过全局依赖。

二、调试时断点死活不触发

默认情况下，sanity start 启动的是编译好的代码（在 dist/ 目录下），断点自然打不进去。要调源码，得让 Sanity 跑在开发模式里，并且指定好调试入口。

具体操作并不复杂。首先确认你的项目里有 sanity.cli.js 或 sanity.cli.ts（Sanity v3+ 推荐用 TypeScript），里面导出了配置对象。然后，在项目根目录的 .vscode/launch.json 里添一段配置：

{
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Sanity dev",
      "runtimeExecutable": "npx",
      "args": ["sanity", "start", "--dev"],
      "console": "integratedTerminal",
      "internalConsoleOptions": "neverOpen",
      "skipFiles": ["/**"]
    }
  ]
}

这里 --dev 参数是核心——它强制 Sanity 使用 src/ 目录下的源码，同时开启文件监听和 sourcemap。如果你用 TypeScript，还要检查一下 tsconfig.json 里 "sourceMap": true 是否启用。

还有一个容易忽略的细节：断点要打在 src/schema 或 src/studio 下的文件里才有效。别白费力气去打断点在 dist/ 或者 node_modules 里，那是不会响应的。

三、改 schema 后热更新失效，或者报 TypeError: Cannot read properties of undefined

这个坑和 VSCode 配置无关，是 Sanity Studio 自己的模块缓存机制在搞鬼。本地开发时频繁改 schema，很容易触发旧模块引用的问题。

重启 sanity start 当然是最稳妥的方案，但每次都重启效率太低。可以先试试快捷键 Ctrl+Shift+P，搜索“Developer: Restart Language Server”，然后刷新浏览器，很多时候能解决。

如果问题还在，那就去检查 schema 文件。一个常见错误是不小心导出了非 object 类型的数据，比如直接导出了一个函数但没调用，或者用了 export default () => ({...}) 却忘了执行它。

还有一个更容易踩的陷阱：循环依赖。比如在 schema/index.js 里用 require('./someType')，但那个文件里又反过来 require 了当前文件。Node 遇到这种情况会返回 undefined，自然就报错了。

建议统一使用 ES modules + import，在 sanity.cli.js 里显式写 module.exports = defineConfig({ ... })，不要混用 CommonJS 和 ESM。

四、VSCode 里哪些插件值得装

Sanity 官方那个插件，说实话已经很久没维护了，不建议装。真正有用的反而是几个基础配置：

• ESLint 插件必须装，前提是项目根目录有 .eslintrc.js（Sanity 官方模板自带）。没有它，import 提示和类型推导都会弱很多。
• Prettier 也推荐装，并在 .prettierrc 里加一行 "semi": false——Sanity 社区普遍习惯无分号风格。
• 在 .vscode/settings.json 里加入下面两行，避免自动格式化打乱 schema 的声明顺序：

{
  "editor.formatOnSa ve": true,
  "ja vascript.format.semicolons": "omit"
}

• 另外建议禁用 Auto Import 这类插件对 defineSchema 的自动补全——它经常把 defineSchema 错补成 defineConfig，导致启动报错。

总结下来，调试 Sanity 不是配个 launch.json 就能一劳永逸的事。关键是要理解它的两层启动逻辑：CLI 命令解析层走的是 Node 进程，而 Studio 渲染层在浏览器里。断点只对前者有效；后者的问题，还是得靠浏览器 DevTools 去查 state 和 network。