vscode 调试 cocos creator 3.x 需手动完成三步：安装 api 插件、生成 jsconfig.json（js 项目禁用 tsconfig.json）、更新 creator.d.ts；web 调试须同步 launch.json 端口，模拟器调试需正确挂载 resources 路径。
VSCode 能完整支持 Cocos Creator 3.x 的代码编辑与联调，但必须手动触发两步关键操作：生成智能提示数据 + 安装 API 适配插件；缺一不可，否则 cc、Node、Component 等核心类型不会被识别。
tsconfig.json 和 jsconfig.json 到底该用哪个？
项目是 JavaScript 编写（默认情况），就只依赖 jsconfig.json；它由 Cocos Creator 在执行「更新 VS Code 智能提示数据」时自动生成并放在项目根目录（assets 同级）。若误点了「添加 TypeScript 项目配置」，会生成 tsconfig.json，反而导致 JS 文件失去智能提示——因为 VS Code 会优先按 TS 规则解析，而 JS 项目没声明类型定义路径。
常见错误现象：cc.log 有提示，但 this.node 报红、event.target 显示 any 类型。
- 确认项目根目录存在
jsconfig.json，且内容包含"baseUrl": "./"和"types": ["creator"] - 删除项目中意外生成的
tsconfig.json（除非你真在写 TS） - 重启 VS Code 或执行
Developer: Reload Window
API 智能提示不更新？先查 creator.d.ts 是否生效
creator.d.ts 是引擎 API 提示的数据源，它不是全局安装的，而是按项目存放的。每次升级 Cocos Creator 或切换自定义引擎后，旧文件不会自动覆盖，必须手动刷新。
使用场景：你在编辑器里看到新 API（比如 sys.isMobile）但在 VS Code 里没提示，大概率是 creator.d.ts 还是老版本。
- 在 Cocos Creator 中打开项目 → 开发者菜单 → VS Code 工作流 → 更新 VS Code 智能提示数据
- 检查项目根目录是否生成/更新了
creator.d.ts（大小通常 >1MB） - 如果用了自定义引擎路径，确保 Cocos Creator 当前加载的是该引擎（菜单底部状态栏可见）
- VS Code 中打开任意
.js文件，输入cc.，等待几秒看是否弹出完整方法列表
调试时断点不命中？重点检查 launch.json 的 url 和端口
Cocos Creator Web 预览服务默认端口是 7456，但编辑器重启或多人共用机器时可能被占用而自动换端口。此时 launch.json 里写死的 url 就会失效，VS Code 无法连接到真实页面，断点永远灰色。
常见错误现象：点击绿色三角开始调试，控制台无输出、断点不触发、浏览器没自动打开。
- 启动 Cocos Creator 并运行 Web 预览，观察右下角状态栏显示的实际端口号（如
http://localhost:62218） - 打开项目下的
.vscode/launch.json，找到url字段，改成对应端口 - 确保
webRoot指向${workspaceFolder}/build/web-mobile（Web 构建输出路径） - 不要依赖「Creator Debug: Launch Chrome」的自动启动逻辑，先手动在浏览器打开预览地址，再在 VS Code 中 Attach 到已打开的标签页（type: "pwa-chrome" + request: "attach"）
模拟器调试失败？路径权限和 .app 包结构是关键
Mac 上调试模拟器最常卡在路径访问：VS Code 无法直接打开 .app 内部资源，project.dev.js 找不到，断点加不上。
性能影响：模拟器 JSB 层调试比 Web 慢，且部分原生行为（如音频播放、传感器）在模拟器中不触发，仅适合逻辑验证。
- Windows 用户直接打开
CocosCreator/resources/cocos2d-x/simulator/win32即可 - Mac 用户必须用 Finder 定位到
CocosCreator.app/Contents/Resources/cocos2d-x/simulator/mac/Simulator.app/Contents/Resources，然后把整个Resources文件夹拖进已关闭所有文件夹的 VS Code 窗口 - 确认拖入后 VS Code 左侧文件树里能看到
src/project.dev.js，否则路径不对 - 断点只能加在
project.dev.js或其require的模块里，不能加在assets下的脚本源码上（它们已被打包）
真正容易被忽略的点是：Cocos Creator 的「VS Code 工作流」菜单命令不是一次性设置，而是按需触发的快照式操作——每次引擎变更、项目迁移、VS Code 重装，都得重新走一遍「安装插件 + 更新提示数据 + 添加调试配置」，没有全局缓存，也没有跨项目继承机制。
