全新ReactJS项目启动开发服务器时卡住的排查求助

• 检查Node.js版本兼容性
  create-react-app对Node版本有明确要求，建议使用LTS版本（如16.x或18.x）。M1 Pro芯片下优先选择官方arm64架构的Node.js，避免依赖Rosetta兼容层。执行node -v查看当前版本，若版本不符，可通过nvm安装适配版本：

  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
  nvm install --lts
  

  安装完成后重新创建项目并启动测试。

• 清理缓存与重建依赖
  缓存损坏或依赖安装不完整可能导致启动停滞，执行以下操作：

  npm cache clean --force
  rm -rf node_modules package-lock.json
  npm install
  

  完成后再次运行npm start。

• 禁用Fast Refresh功能
  Fast Refresh在M1架构环境下偶发兼容性问题，修改项目根目录的package.json，调整start命令：

  "scripts": {
    "start": "FAST_REFRESH=false react-scripts start"
  }
  

  保存后重启项目。

• 排查网络与系统限制
  暂时关闭macOS防火墙（系统设置 > 网络 > 防火墙），并禁用全局代理工具，避免网络规则阻止开发服务器建立连接，之后重新启动项目测试。

• 更换包管理器重试
  npm在M1环境下可能存在依赖安装的兼容性问题，尝试改用yarn或pnpm：
  使用yarn：

  npm install -g yarn
  rm -rf node_modules package-lock.json
  yarn install
  yarn start
  

  使用pnpm：

  npm install -g pnpm
  rm -rf node_modules package-lock.json
  pnpm install
  pnpm start
  

• 查看详细启动日志
  启动时输出verbose日志，定位具体停滞环节：

  npm start --verbose
  

  检查日志中是否有编译超时、依赖报错等具体信息。

• 使用原生ARM终端
  若之前通过Rosetta 2运行终端，改为使用原生ARM终端：打开访达 > 应用程序 > 实用工具 > 终端，右键选择“显示简介”，取消勾选“使用Rosetta打开”，之后重新执行项目创建与启动流程。

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