当你怀揣着刚写好的 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: https://localhost:3000，且浏览器能正常访问该地址。
launch.json中的url必须与终端输出的地址完全一致——不能写成https://127.0.0.1:3000，也不能遗漏https://前缀。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 的路径拼写——它不会像错误提示那样明确告诉你问题所在，只是默默地让断点失去作用。多花几秒钟核对斜杠方向和通配符位置，比重装任何插件都更加有效。
