react - 使用ant design pro提供的脚手架搭建项目，启动项目报错？

Question

根据ant design pro https://pro.ant.design/zh-CN/docs/getting-started提供的快速搭建后台架构方法进行操作，安装了脚手架，依赖也成功安装，但是在启动项目执行npm run start时报错，node版本是22.10.0，
fatal - Error: The specified module could not be found.
\?\F:\project\react-template\node_modules\@umijs\mako\node_modules\@umijs\mako-win32-x64-msvc\mako.win32-x64-msvc.node
没有找到这个模块，我单独安装了@umijs/mako-win32-x64-msvc依赖，还是无效

Answer 1

根据你提供的错误信息，核心问题是系统缺少 mako.win32-x64-msvc.node 模块。这是 Windows 平台下 Umi 框架的底层依赖。以下是系统性的解决方案：

解决方案步骤：

1. 清除缓存并重装依赖
   删除 node_modules 和构建缓存后重新安装：

   rm -rf node_modules
   rm -rf .umi
   rm package-lock.json  # 若使用 yarn 则删除 yarn.lock
   npm cache clean --force
   npm install

2. 检查 Node.js 版本兼容性
   Ant Design Pro 对 Node 20+ 的兼容性更好（当前为 v22.10）
   推荐操作：

   • 降级到 Node 18 LTS（推荐）
   • 或升级到最新稳定版 Node 20.x

3. 安装缺失的二进制模块
   强制安装针对 Windows 的编译版本：

   npm install --save-dev @umijs/mako-win32-x64-msvc

4. 修复可能的文件路径问题
   错误路径中的 \\?\ 表示 Windows 长路径限制问题：

   • 将项目移动到短路径（如 C:\projects\）

   • 在 PowerShell (管理员) 执行：

     Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1

5. 终极解决方案
   若上述无效，尝试切换包管理工具（如用 yarn 代替 npm）：

   npm install -g yarn
   yarn config set registry https://registry.npmmirror.com
   yarn install
   yarn start

补充说明：

• 该错误通常由 依赖未完全编译 或 系统路径限制 导致
• 确保全程使用管理员权限运行命令行
• 80% 类似问题通过「降级 Node + 清除重装」解决

�� 验证建议：在临时目录使用 npm create @umijs/umi-app 创建最小 Umi 项目测试是否正常启动，以排除项目配置问题。