为何Next.js应用部署至Vercel时因@next/swc-darwin-arm64失败？

部署Next.js应用到Vercel时出现以下构建错误：

error @next/swc-darwin-arm64@13.2.4: The platform "linux" is incompatible with this module.
error @next/swc-darwin-arm64@13.2.4: The CPU architecture "x64" is incompatible with this module.
error Found incompatible module.
info Visit https://yarnpkg.com/en/docs/cli/install for documentation about this command.
Error: Command "yarn install" exited with 1
BUILD_FAILED: Command "yarn install" exited with 1

问题1：@next/swc-darwin-arm64是什么，是否属于Next.js的组成部分？ #

• @next/swc-darwin-arm64是Next.js依赖的SWC编译器特定平台版本。SWC是Next.js默认采用的高性能Rust编译器，负责代码转译、压缩等工作，能显著提升构建速度。
• 它属于Next.js的依赖模块，是Next.js为适配macOS（darwin对应macOS）和arm64架构（如M系列芯片）预编译的二进制包，并非Next.js核心代码，但Next.js会根据运行环境自动拉取对应版本。

问题2：若它是Next.js的内部模块，是否意味着Next.js自身存在问题？ #

• 这不是Next.js本身的问题，根源是跨环境依赖缓存不匹配：
  • 你可能在本地M系列芯片的macOS环境下安装过依赖，生成的yarn.lock或node_modules锁定了darwin-arm64版本的SWC；
  • 而Vercel的构建环境是Linux x64系统，拉取依赖时会尝试安装本地锁定的不兼容版本，从而触发报错。

问题3：是否需要向Vercel上报该问题，以及如何修复并完成应用部署？ #

• 无需向Vercel上报，这是常见的跨环境依赖问题，可通过以下步骤修复：
  1. 清理本地依赖缓存：
     • 删除项目根目录的yarn.lock和node_modules；
     • 执行yarn install重新生成适配本地环境的依赖锁文件（注意不要将node_modules提交到代码仓库）；
  2. 配置Yarn兼容多平台：
     • 在项目根目录创建或修改.yarnrc.yml，添加：

       nodeLinker: node-modules
       supportedArchitectures:
         cpu:
           - x64
           - arm64
         os:
           - darwin
           - linux
       

     • 或者在package.json中添加resolutions字段强制统一SWC版本：

       "resolutions": {
         "@next/swc-darwin-arm64": "13.2.4",
         "@next/swc-linux-x64-gnu": "13.2.4"
       }
       

  3. 调整Vercel构建命令：
     • 在Vercel项目设置的「Build & Development Settings」中，将构建命令改为yarn install --ignore-platform，强制Yarn忽略平台差异，自动拉取适配Vercel环境的SWC版本；
  4. 提交修改并重新部署：
     • 将修改后的配置文件和新生成的yarn.lock提交到代码仓库，触发Vercel重新构建即可。

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