Keystone CMS 项目中 keystone dev 报“command not found”，根本原因是未本地安装 keystone CLI（非全局），需在项目根目录执行 npm install 确保 node_modules/.bin/keystone 存在，并重启 VSCode 终端；调试时可用 npx keystone dev 绕过 PATH 问题。
Keystone CMS 项目在 VSCode 中无法识别 keystone 命令？先确认 CLI 安装方式
VSCode 终端里执行 keystone dev 报错 “command not found”，大概率是因为你没在项目本地安装 CLI。Keystone 6+ 不再全局安装 @keystone-6/core 或 keystone CLI，而是依赖 keystone 包自带的二进制入口（通过 package.json 的 "type": "module" 和 bin 字段支持）。
实操建议：
- 确保
package.json中已声明"keystone": "^6.4.0"（或更高稳定版），然后运行npm install（不是npm install -g keystone） - 检查
node_modules/.bin/keystone是否存在；若不存在，删掉node_modules和package-lock.json重装 - VSCode 内置终端需重启才能加载新
node_modules/.bin路径 —— 关闭所有终端页签，再打开一个新终端 - 用
npx keystone dev可绕过 PATH 问题，适合调试启动流程
GraphQL Playground 打不开或 schema 没更新？检查 dev 模式是否启用 GraphQL 端点
Keystone 默认只在 dev 模式下暴露 /api/graphql 和 Playground（/admin 是 Admin UI，不是 GraphQL IDE）。如果访问 http://localhost:3000/api/graphql 显示 404 或白屏，不是前端问题，是服务端未启用。
实操建议：
- 确认启动命令是
keystone dev（不是keystone start或node dist/index.js） - 检查
keystone.ts中config对象是否含graphql: { path: '/api/graphql' }（默认有，但若手动覆盖了graphql配置且设为false就会禁用） - 修改 Schema 后保存，VSCode 应触发热重载；若无反应，看终端日志是否有
? Reloading Keystone config—— 没有则可能是文件监听失效（见下一条） - Windows 用户注意：WSL2 + VSCode Remote 时，需在
keystone.ts的dev: { fileChangeDelayMs: 500 }中加大延迟，避免 chokidar 丢事件
VSCode 断点不生效、console.log 不输出？Node.js 调试配置要匹配 ESM + TypeScript
Keystone 6+ 默认用 ESM（type: "module"）+ TypeScript，直接跑 node . 会报错，VSCode 的默认 Node.js 启动配置也不兼容。断点停不住、console.log 在终端刷出来但调试器看不到，基本是运行时环境和调试器没对齐。
实操建议：
- 在项目根目录加
.vscode/launch.json，内容必须含"runtimeArgs": ["--loader", "ts-node/esm"]（若用 ts-node）或"runtimeArgs": ["--import", "tsx"]（推荐tsx，更快更稳） - 不要用
program指向keystone.ts；应指向生成后的入口，如"program": "${workspaceFolder}/keystone.ts"+"runtimeExecutable": "npx"+"runtimeArgs": ["tsx", "keystone.ts", "dev"] - 确保已安装
tsx：运行npm install --save-dev tsx，否则调试器找不到 loader - 在
keystone.ts顶部加debugger;，启动调试后看 VSCode 是否暂停 —— 若不暂停，检查右下角状态栏是否显示 “TypeScript” 而非 “JavaScript”，否则 TS 类型不会被识别
Schema 修改后 GraphQL Playground 里字段没变？别只刷新页面，要确认类型生成与缓存
改完 list 配置，比如给 User 加个 bio 字段，Playground 里查 users 还是没 bio，常见原因不是代码没生效，而是 GraphQL SDL 缓存或类型未重建。
实操建议：
- 强制清除 Keystone 生成缓存：删掉
.keystone目录（它存了动态生成的 GraphQL Schema、Prisma client、types 等），再重启keystone dev - 检查终端是否输出
✅ Generated GraphQL schema和✅ Generated Prisma client—— 缺任一说明构建中断，常见于schema.prisma语法错误 - Playground 页面按
Ctrl+R（Win/Linux）或Cmd+R（macOS）硬刷新，不要点右上角 “Reload Schema”，那个只拉一次 introspection，不触发服务端重建 - 如果用了
extendGraphqlSchema手动扩展类型，记得返回的extendGraphqlSchema函数必须同步执行，异步逻辑（如await）会导致 schema 初始化失败且无报错
最易被忽略的是 .keystone 目录的隐式持久化 —— 它不像 dist 那样显眼，但一旦残留旧版本生成物，就会让整个 GraphQL 层“卡”在旧 schema 上，连重启都无效。
