Next.js集成@react-pdf-viewer构建报||=语法错误该如何解决

构建抛出SyntaxError: Unexpected token '||='的核心原因是：你引入的pdf.js依赖使用了ES2021新增的逻辑空赋值语法||=，Next.js默认不会转译node_modules目录下的第三方依赖，项目构建时使用的JS解析器版本无法识别该语法，直接解析失败。手动修改node_modules内文件的方式仅本地临时生效，重新执行依赖安装就会被覆盖，可选择以下任意一种方案实现持久修复：

• 方案1：配置Next.js转译指定依赖（优先推荐，无侵入）
  Next.js 13.1及以上版本内置了依赖转译配置，直接在项目根目录的next.config.js中添加配置，让构建工具自动转译pdf相关依赖的高版本语法即可，不需要修改任何第三方源码：

  // next.config.js
  /** @type {import('next').NextConfig} */
  const nextConfig = {
    transpilePackages: ['pdfjs-dist', '@react-pdf-viewer/*'],
  }
  module.exports = nextConfig
  

  如果你使用的是13.1以下版本的Next.js，可以安装next-transpile-modules包实现相同的转译效果，配置逻辑一致。配置完成后重新执行构建即可正常通过。

• 方案2：锁定兼容版本的pdf.js依赖
  未使用||=语法的pdfjs-dist最高兼容版本为2.16.105，可以通过包管理器的resolutions机制，强制项目所有依赖使用该版本的pdfjs-dist，从根源上避免高版本语法问题：

  1. 执行yarn add pdfjs-dist@2.16.105安装兼容版本
  2. 在package.json中添加resolutions字段，锁定版本：

  {
    "resolutions": {
      "pdfjs-dist": "2.16.105"
    }
  }
  

  3. 重新执行yarn install更新依赖锁文件即可，后续部署安装依赖时都会拉取该兼容版本，不会出现语法报错。

• 方案3：通过补丁工具持久化你手动修改的内容
  如果因为项目版本限制无法使用前两种方案，可以用patch-package把你对pdf.js的修改生成持久化补丁，每次安装依赖后自动应用修改：

  1. 先按你之前的操作，手动修改node_modules下pdf.js文件中的||=语法为兼容的||写法
  2. 执行npx patch-package pdfjs-dist，工具会自动在项目根目录生成patches文件夹，存储你对该依赖的修改记录
  3. 在package.json的scripts配置中添加postinstall钩子：

  {
    "scripts": {
      "postinstall": "patch-package"
    }
  }
  

  后续不管是本地还是托管平台执行yarn install，依赖安装完成后都会自动执行补丁脚本，把你的修改应用到新拉取的依赖代码上，不会被还原。

注意：不推荐使用fork私有依赖包的方式修复，后续依赖升级维护成本极高，优先选择前两种方案即可。

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