Windows10中npm start报错'react-scripts'未识别的排查与解决

问题场景 #

Windows 10系统中，执行npm start或npm run start时出现如下报错：

npm start

> app-test@0.1.0 start
> react-scripts start

'react-scripts' is not recognized as an internal or external command,
operable program or batch file.

已尝试的无效操作 #

• npm ci
• 删除node_modules后重新安装依赖
• npm audit fix
• 以管理员身份运行PowerShell执行命令
• 卸载NVM管理的Node v18，重装LTS v16版本
• 确认package.json的dependencies中已包含react-scripts
• 重新创建项目或使用npx create-react-app搭建全新React项目
• 清理npm缓存

特殊现象 #

• 直接执行node node_modules/react-scripts/scripts/start.js可成功启动项目
• 父目录中的旧React项目执行npm i或npm ci后可正常启动，但新建项目必报错
• 在其他磁盘或文件夹中创建React项目可正常运行，推测原工作目录存在权限问题
• 将父开发文件夹复制到其他磁盘、删除原文件夹后重新git克隆恢复结构，均可正常创建并启动项目
• 此前曾遇到类似问题，当时只能通过重装系统解决

重复出现的可能原因分析 #

1. Windows目录ACL权限异常 #

常用工作目录长期读写过程中，可能被杀毒软件、备份工具或其他系统操作修改了目录的访问控制列表（ACL），导致NPM无法正常读取或执行node_modules/.bin下的react-scripts.cmd脚本（Windows下NPM依赖命令的映射文件）。旧项目创建时间早，ACL未被破坏，因此不受影响；直接调用JS文件绕开了NPM的命令解析层，所以能正常运行。

2. NTFS文件系统元数据损坏 #

原工作目录所在的NTFS分区可能存在元数据（如主文件表MFT项）损坏，导致系统无法正确识别node_modules/.bin中的脚本文件。复制目录到其他磁盘或重新克隆时，系统会重建文件元数据，从而修复问题。

3. 本地工具残留的异常缓存 #

常用工作目录可能积累了Git本地缓存、IDE配置缓存，或是NVM、其他包管理工具留下的异常配置残留，这些内容干扰了NPM的依赖解析逻辑。重新克隆项目会清除所有本地残留文件，复制到其他磁盘则脱离了原有环境的干扰，因此问题消失。

4. NPM路径解析局部异常 #

若原工作目录路径包含特殊字符、过长路径，或是存在与NPM路径解析逻辑冲突的本地配置，可能导致NPM无法正确将react-scripts命令映射到对应的脚本文件。直接执行JS文件不需要经过NPM的命令解析流程，因此不受影响。

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