Ubuntu服务器构建Next.js项目遇TextEncoder未定义错误

核心问题分析 #

出现这些错误的核心诱因主要有两点：

• 使用sudo执行npm命令破坏了环境一致性，root用户的Node环境、依赖权限与普通用户不匹配，导致模块加载异常
• ESLint版本与当前Next.js版本不兼容，同时全局API（TextEncoder）在特定环境下未被正确识别

解决方案 #

1. 禁止用sudo执行npm命令（优先推荐） #

sudo会切换到root用户，打乱项目依赖的权限和环境配置，这是最常见的触发原因：

• 修复项目目录权限：

  sudo chown -R $USER:$USER /你的项目绝对路径
  

• 清理旧依赖并重新安装：

  rm -rf node_modules package-lock.json
  npm install
  

• 执行构建：

  npm run build
  

2. 手动添加TextEncoder Polyfill #

如果环境中全局TextEncoder未被正确注入，可通过以下方式修复：

• 安装util包：

  npm install util --save
  

• 修改next.config.js，添加webpack fallback配置：

  module.exports = {
    webpack: (config) => {
      config.resolve.fallback = {
        ...config.resolve.fallback,
        util: require.resolve('util/'),
      };
      return config;
    },
  };
  

• 或者在pages/_app.js顶部添加全局声明：

  import { TextEncoder, TextDecoder } from 'util';
  global.TextEncoder = TextEncoder;
  global.TextDecoder = TextDecoder;
  

3. 对齐ESLint与Next.js版本 #

当前项目Next.js版本为12.0.9，但eslint-config-next为12.1.6，版本不兼容导致报错：

• 修改package.json中的devDependencies：

  "eslint": "8.10.0",
  "eslint-config-next": "12.0.9"
  

• 重新安装依赖：

  npm install
  

4. 确保Node环境一致性 #

检查普通用户与sudo下的Node版本是否一致：

node -v
sudo node -v

如果版本不同，说明root未使用正确的Node环境（比如nvm未配置给root），可使用Node绝对路径执行构建：

/你的Node安装绝对路径/npm run build

内容的提问来源于stack exchange，提问作者Odesola Ajibola Ibrahim