Payload CMS在VSCode中调试失效的主因是Node.js调试协议与TS类型服务协同失准：ts-node绕过V8 Inspector致断点不触发，需改用PAYLOAD_DISABLE_TYPESCRIPT=1 node --inspect -r tsx/esm启动；字段无提示因TS未识别Payload类型定义，须配置typeRoots和@payloadcms/plugin-typescript插件；MongoDB插件看不到数据因集合名含payload_前缀且数据库名为payload；热重载不刷新Admin UI因UI为静态构建产物，需手动重启或监听文件变更触发重建。
VSCode 能直接调试 Payload CMS 项目，但默认配置下会卡在启动、热重载失效、集合字段不提示——核心问题不在 Payload 本身，而在 Node.js 调试协议与 TypeScript 类型服务的协同方式没对齐。
为什么 payload dev 在 VSCode 里断点不生效
Payload 启动时默认用 ts-node 或 tsx 执行 payload.config.ts，而 VSCode 的 pwa-node 调试器默认只注入到主入口（如 server.ts），不会穿透到 ts-node 动态加载的配置文件中。
- 现象：在
access钩子或hooks.beforeChange里打的断点完全不触发 - 根本原因：
ts-node运行时绕过了 V8 Inspector 的源码映射机制，sourceMap路径解析失败 - 解法不是换调试器，而是让 Payload 启动走原生
node+swc编译路径
把 package.json 的 dev 脚本改成：
"dev": "cross-env PAYLOAD_DISABLE_TYPESCRIPT=1 node --inspect=0.0.0.0:9229 -r tsx/esm ./src/server.ts"
关键点：PAYLOAD_DISABLE_TYPESCRIPT=1 强制 Payload 跳过内部 ts-node 加载逻辑；-r tsx/esm 用更轻量的 tsx 提前编译，保留完整 sourceMap。
payload.config.ts 里集合字段没智能提示
TypeScript 语言服务在 VSCode 中无法自动识别 Payload 的 CollectionConfig 类型推导，尤其当字段嵌套深或用了自定义 validate 函数时。
- 常见错误：输入
{ type: 'group', fields: [后，VSCode 不提示Field接口字段 - 原因：Payload 的类型定义依赖于
payload包的types/index.d.ts，但 VSCode 可能未正确解析node_modules中的声明文件 - 实操修复：在项目根目录加
jsconfig.json或tsconfig.json，确保"typeRoots"包含node_modules/payload/types
最小可用 tsconfig.json：
{
"compilerOptions": {
"typeRoots": ["./node_modules/payload/types", "./node_modules/@types"],
"plugins": [{ "name": "@payloadcms/plugin-typescript" }]
}
}
注意：@payloadcms/plugin-typescript 是社区插件，非官方，但能补全 fields 数组内联类型推导。
集合数据在 VSCode MongoDB 插件里看不到
Payload 默认用 MongoDB，但本地开发时如果直接连 mongodb://localhost:27017，可能看到空库或旧集合——因为 Payload 会按 collection.slug 自动加前缀（如 payload_），且集合名大小写敏感。
- 检查真实集合名：在 MongoDB Playground 运行
db.getCollectionNames()，找类似payload_posts而非posts - VSCode MongoDB 插件需显式指定数据库名，默认是
test，Payload 用的是payload（由PAYLOAD_DATABASE_URI决定） - 连接字符串示例：
mongodb://127.0.0.1:27017/payload?directConnection=true，末尾?directConnection=true避免 MongoDB 插件因 replica set 检测失败而拒绝连接
修改集合后热重载不刷新管理界面
Payload 的 Admin UI 是静态构建产物，dev 模式下只监听 payload.config.ts 和 collections/** 文件变更，但不会自动重建 UI bundle。
- 现象：改了
fields数组，保存后浏览器页面无变化，F5 刷新才生效 - 这不是 bug，是设计取舍：Payload 把 Admin UI 视为“配置的渲染结果”，而非运行时动态生成
- 快速验证方式：在终端 Ctrl+C 停掉服务，再
npm run dev，比等 HMR 更可靠 - 进阶方案：用
chokidar-cli监听collections目录，触发payload generate:admin（需 Payload v3.0+）
真正容易被忽略的是：Payload 的热重载只响应 .ts 文件内容变更，如果你用 git checkout 切分支导致文件时间戳没变，VSCode 的文件监视器可能压根不触发重载——此时必须手动重启进程。
