React(TypeScript)项目使用环境变量时Webpack构建报错求助

问题概述 #

开发首个React+TypeScript项目时，添加DefinePlugin/DotEnvPlugin等环境变量插件后，执行npm run build触发TypeError: Cannot read properties of undefined (reading 'assets')报错。初始仅配置HtmlWebpackPlugin可正常构建，后续即使仅保留该插件也出现相同报错，移除后则报path未定义。项目结构如下：

ls-app
  \src
    \environments
    \libs
    .env.development
    .env.production
  webpack.config.js

核心依赖版本：webpack@5.94.0、@babel/core@7.25.2等。

排查与解决步骤 #

1. 修复webpack基础配置缺失 #

path未定义报错说明配置中未正确引入path模块或未配置output字段，这是后续assets读取失败的根源之一。在webpack.config.js顶部添加：

const path = require('path');

并补充完整的output配置：

module.exports = {
  // ...其他配置
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].[contenthash].js',
    clean: true, // 每次构建清空dist目录
    assetModuleFilename: 'assets/[hash][ext][query]' // 明确资源输出路径，避免assets读取异常
  },
  // ...插件配置
};

2. 检查HtmlWebpackPlugin配置正确性 #

确保HtmlWebpackPlugin的template路径正确，且模板中无错误引用assets的写法。示例正确配置：

const HtmlWebpackPlugin = require('html-webpack-plugin');

module.exports = {
  // ...其他配置
  plugins: [
    new HtmlWebpackPlugin({
      template: './public/index.html', // 匹配项目实际HTML模板路径
      inject: 'body',
      title: 'LS App'
    }),
    // ...其他插件
  ]
};

若使用自定义HTML模板，删除模板中类似<%= htmlWebpackPlugin.options.assets %>的错误写法，webpack5会自动注入资源，无需手动引用。

3. 规范环境变量插件配置 #

方式一：使用webpack内置DefinePlugin

需确保环境变量以process.env.XXX格式注入，且值为字符串（需额外包裹引号）：

const webpack = require('webpack');
const dotenv = require('dotenv');
// 根据环境加载对应env文件
const env = dotenv.config({ path: `.env.${process.env.NODE_ENV || 'development'}` }).parsed;

// 将env对象转换为DefinePlugin可识别的格式
const envKeys = Object.keys(env).reduce((prev, next) => {
  prev[`process.env.${next}`] = JSON.stringify(env[next]);
  return prev;
}, {});

module.exports = {
  // ...其他配置
  plugins: [
    new webpack.DefinePlugin(envKeys),
    new HtmlWebpackPlugin(/* ...配置 */)
  ]
};

方式二：使用dotenv-webpack插件

安装插件后直接配置，无需手动解析env：

npm install dotenv-webpack --save-dev

webpack配置中添加：

const Dotenv = require('dotenv-webpack');

module.exports = {
  // ...其他配置
  plugins: [
    new Dotenv({
      path: `.env.${process.env.NODE_ENV || 'development'}` // 加载对应环境的env文件
    }),
    new HtmlWebpackPlugin(/* ...配置 */)
  ]
};

4. 清理缓存与重置依赖 #

• 删除依赖文件后重新安装：

rm -rf node_modules package-lock.json
npm install

• 清理webpack缓存，修改package.json的build脚本：

"scripts": {
  "build": "NODE_ENV=production webpack --mode production --no-cache"
}

5. 逐步排查插件冲突 #

将插件逐个添加到配置中，每次添加后执行npm run build，定位触发报错的具体组合：

1. 仅保留output和HtmlWebpackPlugin，确认构建正常；
2. 再添加环境变量插件，测试是否报错；
3. 若报错，检查插件配置参数是否符合webpack5版本要求。

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