VSCode终端无法直接运行gatsby new，因其默认以非登录shell启动，不加载nvm/fnm等shell配置，导致PATH缺失、命令未识别或Node版本错乱；需通过安装Shell Command或切换默认终端配置解决。
创建 Gatsby 项目时为什么不能直接用 gatsby new 在 VSCode 终端里跑？
因为 VSCode 内置终端默认不加载 shell 的完整环境（尤其是 Node.js 版本管理工具如 nvm 或 fnm 的配置），容易报 command not found: gatsby 或版本错乱。不是 VSCode 的问题，是终端启动方式导致的 PATH 缺失。
实操建议：
- 在 VSCode 中先用
Cmd+Shift+P（macOS）或Ctrl+Shift+P（Windows/Linux）打开命令面板，输入并选择Shell Command: Install 'code' command in PATH—— 这能让 VSCode 终端继承系统 shell 环境 - 或者改用 VSCode 的「集成终端」→ 右键终端标签 →
Select Default Profile→ 选带zsh或bash（而非pwsh或cmd）的配置 - 验证是否生效：在新终端中运行
which gatsby和nvm current，确认路径和 Node 版本正确
GraphQL 查询在 VSCode 里不提示、报红、Cannot query field 怎么办？
Gatsby 的 GraphQL 类型是在构建时动态生成的，VSCode 默认无法感知这些运行时类型，所以 graphql 标签里的字段不会自动补全，ESLint 也可能误报。
实操建议：
- 必须安装插件：
GraphQL for VSCode（by Prisma） +Gatsby Theme UI（非必需但有助于识别useStaticQuery） - 在项目根目录加
.graphqlrc.yml，内容为：schema: http://localhost:8000/__graphql
—— 注意：要先gatsby develop起服务，否则地址不可达 - 如果用
useStaticQuery，确保查询是顶层 const 声明（不能包在函数里），且字段名拼写与gatsby-config.js或数据源完全一致（大小写敏感） - 类型缓存有时滞后：修改了
gatsby-node.js或新增了 Markdown 文件后，重启gatsby develop并按Cmd+Shift+P→GraphQL: Reload Schema
gatsby-browser.js 和 gatsby-ssr.js 修改后热更新不生效？
这两个文件只在开发服务器启动时读取一次，不是 React 组件，不参与 HMR（热模块替换）。改完保存，VSCode 不会自动刷新，浏览器也不会响应变更。
实操建议：
- VSCode 里可配置保存时自动重启开发服务：在
.vscode/tasks.json中加一个 task，命令为kill -SIGUSR2 $(cat .cache/process.pid) || echo "no pid"（仅 macOS/Linux），或更稳妥地用npm run clean && gatsby develop - 日常调试更推荐加日志：在
gatsby-browser.js开头加console.log('browser loaded', Date.now())，改完保存后看控制台时间戳是否更新，快速判断是否重载成功 - 注意：
gatsby-ssr.js的修改在gatsby develop下基本无效（SSR 逻辑被绕过），必须用gatsby build && gatsby serve验证
怎么快速定位 GraphQL 数据没进组件的原因？
常见陷阱不是语法错，而是数据流断在中间环节：source plugin 没拉到数据、filter 条件写死、或者 createPages 时 context 传丢了。
实操建议：
- 打开
http://localhost:8000/___graphql，手动执行相同查询，确认数据存在且结构符合预期 —— 如果这里都为空，问题一定出在 source 或gatsby-node.js - 在页面组件里加
console.log(data)，注意看输出是否为undefined或null；如果是，检查pageContext是否被createPage正确注入（字段名大小写、嵌套层级） - 用 Chrome DevTools 的
Network标签过滤graphql请求，查看 response payload，比 VSCode 里的错误提示更原始、更真实 - 别依赖 IDE 的自动导入：手动写
import { graphql } from 'gatsby'，避免因路径别名或 TypeScript 配置导致graphql变量未定义
GraphQL 类型是动态生成的，而 VSCode 是静态分析器——这个根本差异决定了所有“不提示”“报红”问题的本质。每次怀疑插件失效前，先确认 gatsby develop 正在运行，且 .graphqlrc.yml 指向的是当前开发端口。
