Gridsome项目VSCode调试需手动配launch.json、先启动dev server、确保source map启用；常见问题源于端口不匹配、webRoot错位及source map未开启。
Gridsome 项目在 VSCode 中无法直接“一键调试”，必须手动配 launch.json 并确保开发服务器已启动；断点不生效、页面白屏或“未连接”基本都卡在这三处：端口不匹配、webRoot 错位、source map 未启用。
确认项目已能正常启动
VSCode 不负责启动 Gridsome，只负责连接已运行的 dev server。先在终端执行：
npm run develop
或（如果用了 yarn）：
yarn develop
确保控制台输出类似 Project is running at http://localhost:8080/，且浏览器能打开页面。若报错或无响应，launch.json 再准也连不上。
- 检查
package.json是否含"develop": "gridsome develop"脚本；没有就补上 - Gridsome 默认端口是
8080，但可通过gridsome.config.js的host/port修改；launch.json中的url必须和实际地址完全一致（含协议、端口、斜杠） - 不要用
file://协议——Gridsome dev server 是 HTTP 服务，file://下 source map 根本不会加载
装插件 + 配 launch.json
必须安装 Debugger for Chrome 或 Debugger for Edge（根据你常用浏览器选其一）。然后在项目根目录创建 .vscode/launch.json，内容如下：
{
"version": "0.2.0",
"configurations": [
{
"type": "chrome",
"request": "attach",
"name": "Attach to Gridsome",
"port": 9222,
"webRoot": "${workspaceFolder}",
"url": "http://localhost:8080/",
"sourceMapPathOverrides": {
"webpack:///src/*": "${webRoot}/src/*",
"webpack:///./src/*": "${webRoot}/src/*"
}
}
]
}
-
request推荐用"attach"：先手动启服务，再 F5 连接，比"launch"更稳定 -
port是 Chrome DevTools 的调试端口，默认9222；若被占用或改过，需同步改 Chrome 启动参数（如加--remote-debugging-port=9223） -
webRoot必须是"${workspaceFolder}"，不是"${workspaceFolder}/src"；否则pages/或layouts/下的文件断点会失效 -
sourceMapPathOverrides是关键：Gridsome 基于 Vue 2 + webpack，必须保留webpack:///前缀映射；删掉或写成"*": "${webRoot}/*"会导致断点灰色
确保 source map 已启用
Gridsome 默认开启 source map，但如果你改过 gridsome.config.js，请确认没关掉：
module.exports = {
configureWebpack: {
devtool: 'source-map' // 必须存在，不能是 'eval' 或 false
}
}
- 生产构建（
gridsome build）默认关 source map，但调试只关心develop模式 - 若用的是旧版 Gridsome（
），可能需在 <code>plugins里显式加@gridsome/plugin-webpack-visualizer来验证 source map 是否生成 - 在 Chrome DevTools 的 Sources 面板中，展开
webpack://，能看到./src/下的原始文件，才说明映射成功
最常被忽略的一点：attach 模式下，VSCode 不会自动打开浏览器；你得自己访问 http://localhost:8080/，等页面加载完成、Vue 实例挂载完毕，再按 F5 —— 否则调试器连上空页，断点全无效。
