NextJS项目中使用ky-universal时报Cannot use import statement outside a module错误

报错核心原因 #

触发该报错的本质是模块规范不匹配：ky-universal 底层依赖的 node-fetch 官方包为纯ES模块格式，而Next.js默认的Node服务侧逻辑、旧版本构建链路默认以CommonJS规则解析第三方依赖，遇到ES模块原生的import语法时，就会抛出Cannot use import statement outside a module的语法错误。

可落地修复步骤 #

• 开启第三方依赖的构建转译
  在项目根目录的next.config.js中添加内置配置，强制Next.js构建链路对ky-universal及其依赖的node-fetch做语法转译，跳过原生Node模块的直接解析：

  /** @type {import('next').NextConfig} */
  const nextConfig = {
    transpilePackages: ['ky-universal', 'node-fetch']
  }
  module.exports = nextConfig
  

  该配置从Next.js 13.0版本开始内置支持，无需额外安装第三方插件。
• 按运行场景匹配对应依赖
  当前的测试请求逻辑写在客户端组件的useEffect钩子中，这类浏览器端运行的场景完全不需要引入ky-universal：
  • 客户端发请求直接使用原生适配浏览器环境的ky包即可，引入方式为import ky from 'ky'，不会触发任何Node端依赖的解析问题
  • 仅在服务端运行的逻辑（如服务端组件、Route Handler、getServerSideProps等场景）单独引入ky-universal，不要把该依赖的引入逻辑放在会被同步打包到客户端的公共组件代码里
• 低版本Next.js适配
  如果使用的是Next.js 12及更早的、无内置transpilePackages能力的版本，需要搭配next-transpile-modules插件，将ky-universal、node-fetch加入转译范围，避免ES模块语法被直接放到CommonJS执行环境。

注意：不要在客户端层静态引入ky-universal，该操作会把Node端专用的node-fetch依赖一同打入客户端包，既会增大包体积，也是触发模块解析报错的高频诱因。

内容的提问来源于stack exchange，提问作者oldo.nicho