VSCode运行React项目：从npm安装到启动调试

当你怀揣着刚写好的 React 项目，在终端运行 npm install 且没有报错后，信心满满地输入 npm start——结果终端却提示“command not found: react-scripts”或“Cannot find module 'react-scripts'”。别急着责怪网络，问题多半出在 node_modules 目录未能完整安装，例如安装过程被 Ctrl+C 中断、磁盘空间不足，或者不小心误删了该目录。

请先确认项目根目录下是否存在 node_modules 文件夹和 package-lock.json 文件。若缺失，说明之前的 npm install 并未成功运行完毕。此时不要急着手动删除并重试——建议优先使用 npm ci，它会严格依据锁文件进行安装，比 npm install 更加可靠。如果你之前使用的是 pnpm 或 yarn，就更简单了：混合使用命令必然出错，比如用 pnpm install 后必须用 pnpm start，否则二进制文件不会出现在 npm 的路径中。还有一个容易忽略的细节：CRA 项目中的 react-scripts 仅存在于 devDependencies 中，若你使用了 npm install --production，它会直接被跳过——结果就是 npm start 找不到它。

为什么 npm install 之后 npm start 依然报错？

常见现象是 npm install 执行成功，但运行 npm start 时提示 command not found: react-scripts 或 Cannot find module 'react-scripts'。这并非网络问题，而是 node_modules 未完整安装或被误删所致。

• 检查项目根目录是否包含 node_modules 文件夹和 package-lock.json 文件；若缺失，说明 npm install 实际上并未完成（例如被 Ctrl+C 中断、磁盘空间不足）。
• 不要手动删除 node_modules 后仅运行 npm i —— 优先使用 npm ci，它能严格遵循 package-lock.json 安装依赖，更稳定可靠。
• 如果使用了 pnpm/yarn，切勿混用 npm 命令；pnpm install 后必须使用 pnpm start，否则无法找到对应的二进制文件。
• CRA 项目依赖于 react-scripts，它只属于 devDependencies，当执行 npm install --production 时会被跳过，从而导致 npm start 失败。

npm start 成功启动，但 VSCode 断点无效

开发服务器已运行，浏览器可以正常打开页面，但你在 VSCode 中设置的断点却始终不触发？90% 的情况是 sourcemap 映射路径不匹配。调试器本身并不启动服务，它只是连接到已运行的开发服务器。因此，请先确认终端输出中已出现 Local: http://localhost:3000，且浏览器能正常访问该地址。

• launch.json 中的 url 必须与终端输出的地址完全一致——不能写成 http://127.0.0.1:3000，也不能遗漏 http:// 前缀。
• webRoot 应指向构建产物的根目录：CRA 项目设置为 "${workspaceFolder}/public"，Vite 项目则设置为 "${workspaceFolder}/dist"。
• sourceMapPathOverrides 的配置必须与打包器生成的 sourcemap 路径匹配。CRA 项目使用 "webpack:///src/*": "${webRoot}/../src/*"，Vite 项目使用 "*": "${webRoot}/../src/*"。少一个斜杠或多一个星号，断点就会悄无声息地失效，且不会抛出任何错误——这正是最令人头疼的地方。

调试类型应选择 pwa-chrome 还是 chrome？

VSCode 1.70 及以上版本已弃用旧版的 chrome 调试器。如果你继续使用 type 为 "chrome" 的配置，即使本地 Chrome 安装正常，也会提示 Can't find Chrome。因此，必须将类型改为 "pwa-chrome"。同时，请确保安装了官方插件 Debugger for Edge 或 Debugger for Chrome（后者虽然名称包含 Chrome，但已支持新版 PWA 协议）。

• 在 .vscode/launch.json 文件中，type 字段必须设置为 "pwa-chrome"，而非 "chrome"。
• 如果 Chrome 安装在非默认路径（例如便携版），需显式指定 runtimeExecutable，例如 "runtimeExecutable": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"。

JSX 在编辑器中标红，但项目可以正常运行，如何关闭此提示？

VSCode 内置的 JavaScript 语言服务默认不识别 JSX 语法，因此会给出红色波浪线提示——这与 ESLint 是完全不同的机制。关闭此功能并不会影响 ESLint 的规则校验。

• 打开设置（Ctrl+, 或 Cmd+,），搜索 javascript.validate.enable，将其设为 false。
• 保留 ESLint 插件，并确保项目根目录包含 .eslintrc.js 配置文件（推荐使用 eslint-config-react-app）。
• 如果是 TypeScript 项目，请检查 tsconfig.json 中是否包含 "jsx": "react-jsx"；如果是 JavaScript 项目，则需要在 jsconfig.json 中添加 "compilerOptions": { "jsx": "react-jsx" }。

归根结底，真正阻碍你的往往不是代码逻辑本身，而是 launch.json 中那行 sourceMapPathOverrides 的路径拼写——它不会像错误提示那样明确告诉你问题所在，只是默默地让断点失去作用。多花几秒钟核对斜杠方向和通配符位置，比重装任何插件都更加有效。