Next.js执行npm run dev命令时加载SWC二进制文件失败的问题求助

问题场景 #

当你执行npm run dev启动Next.js项目时，出现了找不到SWC二进制模块的错误，完整报错日志如下：

PS D:\web-development\new-project\explore> npm run dev
> dev
> next dev
ready - started server on 0.0.0.0:3000, url: http://localhost:3000
错误: 找不到指定的模块。
\\?\D:\web-development\new-project\explore\node_modules\@next\swc-win32-x64-msvc\next-swc.win32-x64-msvc.node
    at Object.Module._extensions..node (node:internal/modules/cjs/loader:1179:18)
    at Module.load (node:internal/modules/cjs/loader:975:32)
    at Function.Module._load (node:internal/modules/cjs/loader:822:12)
    at Module.require (node:internal/modules/cjs/loader:999:19)
    at require (node:internal/modules/cjs/helpers:102:18)
    at loadNative (D:\web-development\new-project\explore\node_modules\next\dist\build\swc\index.js:84:28)
    at loadBindings (D:\web-development\new-project\explore\node_modules\next\dist\build\swc\index.js:41:32)
    at async Object.isWasm (D:\web-development\new-project\explore\node_modules\next\dist\build\swc\index.js:146:20)
    at async D:\web-development\new-project\explore\node_modules\next\dist\build\webpack\loaders\next-swc-loader.js:62:178 {
  code: 'ERR_DLOPEN_FAILED'
}
error - 加载SWC二进制文件失败，更多信息请查看：https://nextjs.org/docs/messages/failed-loading-swc
PS D:\web-development\new-project\explore>

解决办法 #

我之前在Windows环境下碰到过一模一样的问题，试了几个方法都能解决，你可以按顺序尝试：

• 清理依赖并重新安装
  这是最常见的修复方式，先删除损坏的node_modules和锁文件，让npm重新下载所有依赖：

  # Windows PowerShell执行以下命令
  Remove-Item -Recurse -Force node_modules
  Remove-Item package-lock.json
  npm install
  

  安装完成后再执行npm run dev验证是否恢复正常。

• 清理Next.js缓存
  Next.js的.next缓存文件夹有时候会残留损坏的编译文件，直接删除它再重启项目：

  Remove-Item -Recurse -Force .next
  npm run dev
  

• 手动安装对应平台的SWC包
  报错里明确提到缺失@next/swc-win32-x64-msvc这个包，你可以手动安装它来补全依赖：

  npm install @next/swc-win32-x64-msvc
  

• 回退到稳定的Next.js版本
  如果是最近升级了Next.js版本才出现的问题，可能是新版本的SWC适配存在bug，回退到之前能正常运行的稳定版本即可，比如：

  npm install next@13.4.12 # 替换成你之前使用的具体版本号
  

• 强制使用SWC的Wasm版本
  如果你的Windows环境对原生SWC二进制兼容性较差，可以强制Next.js使用Wasm版本的SWC：
  方法一：在next.config.js中添加配置：

  module.exports = {
    experimental: {
      forceSwcTransforms: true,
      swcLoader: true,
    },
  };
  

  方法二：设置环境变量后启动项目：

  set NEXT_SWC_USE_WASM=1
  npm run dev
  

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