React报错Module not found: 导入文件超出src目录解决方案

报错信息 #

Module not found: Error: You attempted to import /User/Developer/app/node_modules/react-refresh/runtime.js which falls outside of the project src/ directory. Relative imports outside of src/ are not supported.
You can either move it inside src/, or add a symlink to it from project's node_modules/.

报错核心说明 #

这个报错是Create React App脚手架的安全限制触发的，默认不允许引用src目录外的相对路径资源。注意：报错自带的「移动文件到src、添加软链」是通用兜底提示，不要直接按这个操作修改依赖文件，会破坏项目依赖结构，90%以上的场景是依赖安装异常、缓存冲突、路径写错导致的误报，按以下优先级排查即可：

修复步骤 #

• 清理缓存并重装依赖（最高优先级，能解决绝大多数场景）
  先终止正在运行的本地开发服务，在项目根目录执行对应命令：

  # 清空现有依赖和锁文件
  rm -rf node_modules package-lock.json yarn.lock pnpm-lock.yaml
  # 按自己使用的包管理器选择执行，重新安装依赖
  npm install
  # 或 yarn install / pnpm install
  # 重置脚手架缓存后重启项目
  npm start -- --reset-cache
  

  这类报错最常见的诱因是依赖安装过程中路径映射表异常，导致脚手架把node_modules内的合法依赖识别成了src外的非法路径，清缓存重装后路径映射会恢复正常。
• 排查业务代码的导入路径
  全局搜索项目内的导入语句，检查是否存在写错的相对路径：比如多写了../跳出了src目录，或者导入第三方依赖时误写了带node_modules的完整绝对路径。导入npm依赖直接写包名即可，比如导入React的正确写法是import React from 'react'，不需要写完整的node_modules路径。
• 修复依赖版本兼容问题
  如果前两步操作后仍然报错，检查package.json内react-scripts、react、react-dom的版本是否匹配，版本不兼容会导致热更新依赖react-refresh的路径解析出错，可以手动安装兼容版本的react-refresh后重启：

  npm install react-refresh@0.11.0 --save-dev
  

• 校验运行目录与文件完整性
  确认你执行npm start的位置是项目根目录，不要在src或者其他子目录下运行启动命令；同时检查根目录下node_modules/react-refresh/runtime.js文件是否存在，文件缺失说明依赖没有安装完整，回到第一步重新执行重装操作即可。

内容的提问来源于stack exchange，提问作者aaronmbmorse