本地正常的环境变量部署到Netlify后显示undefined求助

DevOps 小满

2026-8-25

解决Netlify部署后API_KEY环境变量为undefined的问题

问题根源

本地运行正常但Netlify部署后变量显示undefined，核心原因是webpack构建时未正确注入Netlify提供的环境变量，当前DefinePlugin直接序列化整个process.env的配置，在Netlify构建环境下可能导致目标变量未被正确捕获，另外多数情况会忽略「设置环境变量后需重新触发构建」的要求。

修复步骤

1. 修正webpack的DefinePlugin配置

修改webpack.common.js中的DefinePlugin，避免序列化整个process.env，只明确注入需要的API_KEY，减少冗余同时避免变量丢失：

const HtmlWebpackPlugin = require('html-webpack-plugin');
const webpack = require('webpack');
// 保留dotenv加载本地.env，方便本地开发调试
require('dotenv').config({ path: './.env' });

module.exports = {
    entry: './src/index.js',
    plugins : [
        new HtmlWebpackPlugin({
            template: './src/template.html'
        }),
        new webpack.DefinePlugin({
            'process.env.API_KEY': JSON.stringify(process.env.API_KEY)
        })
    ],
    module: {
        rules: [
            {
                test: /\.css$/,
                use: ['style-loader', 'css-loader']
            }
        ]
    }
}

2. 确认Netlify配置并重新构建

检查Netlify后台「Site settings > Build & deploy > Environment > Environment variables」中，变量名是否为API_KEY（大小写必须与代码中的process.env.API_KEY完全匹配）
设置完成后，必须在Netlify的「Deploys」页面点击「Trigger deploy」->「Deploy site」重新构建，旧的构建缓存不会自动加载新的环境变量

3. 验证生产构建配置

确保webpack.prod.js正确合并了webpack.common.js的配置，保证DefinePlugin在生产构建中生效，示例prod配置如下：

const { merge } = require('webpack-merge');
const common = require('./webpack.common.js');

module.exports = merge(common, {
    mode: 'production',
    // 其他生产环境专属配置...
});