根本原因是全局未安装sanity-cli或VSCode终端未继承系统PATH，需先在系统终端验证sanity命令是否可用，再通过code --new-window启动VSCode继承环境，或局部安装后用npx调用。
启动 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 环境 - 若仍不行，直接局部安装 CLI：在项目根目录运行
npm install --save-dev @sanity/cli，然后用 npx 调用：npx sanity start
调试 sanity start 时断点不生效
默认 sanity start 启动的是编译后的产物（dist/），源码断点自然无效。必须启用开发模式并指定调试入口：
- 确保项目有
sanity.cli.js或sanity.cli.ts（新版 Sanity v3+ 推荐用 TS），里面导出配置对象 - 在
.vscode/launch.json中添加以下配置（注意runtimeExecutable和args）：
{
"configurations": [
{
"type": "node",
"request": "launch",
"name": "Sanity dev",
"runtimeExecutable": "npx",
"args": ["sanity", "start", "--dev"],
"console": "integratedTerminal",
"internalConsoleOptions": "neverOpen",
"skipFiles": ["<node_internals>/**"]
}
]
}
-
--dev是关键——它强制使用未编译的源码（src/），且开启 watch 和 sourcemap - 如果项目用 TypeScript，确保
tsconfig.json中"sourceMap": true已启用 - 断点打在
src/schema或src/studio下的文件里才有效，别打在dist/或 node_modules 里
修改 schema 后热更新失效或报 TypeError: Cannot read properties of undefined
这不是 VSCode 配置问题，而是 Sanity Studio 的模块缓存机制导致的。本地开发时，频繁改 schema 容易触发 stale module 引用：
- 重启
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 混用
VSCode 插件推荐与必要设置
不用装“Sanity”官方插件（它基本没维护），真正有用的只有几个基础配置：
- 装
ESLint插件，并确保项目根目录有.eslintrc.js（Sanity 官方模板自带），否则 import 提示、类型推导会弱很多 - 装
Prettier，并在.prettierrc里加"semi": false（Sanity 社区普遍用无分号风格） - 在
.vscode/settings.json加这两项，避免自动格式化破坏 Sanity 的 schema 声明顺序：
{
"editor.formatOnSave": true,
"javascript.format.semicolons": "omit"
}
- 禁用
Auto Import类插件对defineSchema的自动补全——它常把defineSchema错补成defineConfig，导致启动失败
调试 Sanity 不是配个 launch.json 就完事，核心在于理解它的两层启动逻辑：CLI 命令解析层（Node 进程）和 Studio 渲染层（浏览器）。断点只对前者有效，后者要用浏览器 DevTools 查 state 和 network。
