企业官网建设流程全解析

• 前端
• 开发工具
• 前端构建

导读

本文围绕 Snowpack 官方环境变量插件@snowpack/plugin-dotenv展开，系统讲解它如何借助 dotenv 与dotenv-expand从项目.env文件中加载环境变量、按NODE_ENV分层合并多份文件、以及如何通过SNOWPACK_PUBLIC_前缀安全地把变量注入到前端代码。读完本文，你将掌握该插件的安装配置、两个可选参数（dir/expand）的语义与默认值、.env文件的优先级规则，以及其底层实现与测试验证方式，能直接在 Snowpack 项目中落地可复用的环境变量方案。

一、插件定位：Snowpack 环境变量的三种设置方式之一

Snowpack 官方文档 docs/reference/environment-variables.md 给出了三种设置环境变量的途径：

1. CLI 方式：在启动命令前直接注入，例如SNOWPACK_PUBLIC_API_URL=api.google.com snowpack dev；
2. 配置文件方式：在snowpack.config.mjs中通过env对象传入（v3.1.0 起推荐），这些变量无需SNOWPACK_PUBLIC_前缀也会出现在import.meta.env上；
3. 插件方式：即本文主角@snowpack/plugin-dotenv，从.env文件批量加载环境变量。

其中插件方式最适合"把密钥与配置写在文件里、不入库"的团队协作场景，也是 Create React App / Webpack 用户最熟悉的.env工作流在 Snowpack 中的对应实现。

为什么必须使用 SNOWPACK_PUBLIC_ 前缀

插件的 README 明确提醒：Snowpack 只识别以SNOWPACK_PUBLIC_开头的环境变量。原因在于前端应用的所有代码最终都会下发到浏览器，若不加以区分，很容易把服务端密钥、数据库口令等敏感信息意外暴露给公网。前缀本身就是一个醒目的提示：凡带此前缀的变量都会被"共享给全世界"。

这一规则并非插件私有逻辑，而是 Snowpack 核心的强制过滤。在 build-import-proxy.ts 中，核心实现通过PUBLIC_ENV_REGEX = /^SNOWPACK_PUBLIC_.+/筛选process.env，不匹配的变量一律不会注入前端。也就是说，plugin-dotenv负责把.env文件读入process.env，而能否进入浏览器代码，最终由核心的getSnowpackPublicEnvVariables()把关。

二、安装与快速接入

插件以 npm 包形式发布（包名@snowpack/plugin-dotenv，当前仓库内版本为 2.2.0，见 package.json），依赖dotenv@^8.2.0与dotenv-expand@^5.1.0。

npm install --save-dev @snowpack/plugin-dotenv

在snowpack.config.mjs中注册插件：

// snowpack.config.mjs export default { plugins: ['@snowpack/plugin-dotenv'], };

然后在项目根目录创建.env文件：

# .env SNOWPACK_PUBLIC_ENABLE_FEATURE=true

启动snowpack dev或snowpack build后，SNOWPACK_PUBLIC_ENABLE_FEATURE即可通过import.meta.env在应用中读取，例如：

if (import.meta.env.SNOWPACK_PUBLIC_ENABLE_FEATURE === 'true') { // 启用某个前端功能 }

三、插件选项：dir 与 expand

插件支持两个可选参数（见 README.md 的 Options 表格），传参方式为数组内对象形式：

// snowpack.config.mjs export default { plugins: [['@snowpack/plugin-dotenv', {dir: './env', expand: false}]], };

这两处默认值在 plugin.js 中有明确实现：

const dir = options && options.dir ? options.dir.toString() : '.'; const expand = options && options.expand !== undefined ? options.expand : true;

dir：把 .env 从项目根目录移到子目录

当团队希望把所有环境文件收拢到独立目录（如env/、config/）时，可用dir指定相对路径。实现中会执行path.resolve(process.cwd(), dir, dotenvFile)，即以当前工作目录为基准解析，因此dir使用相对路径即可。

expand：控制变量展开

.env文件中允许出现${VAR}形式的引用。开启expand: true（默认）时，dotenv-expand会把这类引用替换为已定义变量的值；关闭后则保留原始字符串。这在后续"变量展开"小节会结合测试快照具体说明。

四、.env 文件优先级与合并规则

插件按照固定顺序加载最多 4 类文件（plugin.js）：

const dotenvFiles = [ NODE_ENV && `.env.${NODE_ENV}.local`, // 1. 环境专属 + local，优先级最高 NODE_ENV !== 'test' && `.env.local`, // 2. 通用 local（test 环境下跳过） NODE_ENV && `.env.${NODE_ENV}`, // 3. 环境专属 '.env', // 4. 通用文件，优先级最低 ].filter(Boolean);

四条规则要点：

• 越靠前的文件优先级越高，同名变量由先加载的文件决定（dotenv本身不会覆盖已存在的变量）；
• test环境下刻意跳过.env.local，保证所有人的测试结果一致；
• NODE_ENV未设置时（例如undefined），仅加载.env；
• 文件不存在会被静默跳过，不产生告警。

加载优先级验证

仓库为插件配套了完整的测试夹具（plugins/plugin-dotenv/test/env），在每个目录下都准备了.env、.env.local、.env.development、.env.development.local、.env.production、.env.production.local、.env.test、.env.test.local全套文件，其中.env里所有占位值都写成ENV，供快照比对覆盖关系。

测试快照 test/snapshots/plugin.test.js.snap 验证了合并结果：

• NODE_ENV=development时，__DOTENV_DEVELOPMENT、__DOTENV_DEVELOPMENT_LOCAL取到各自专属文件里的DEVELOPMENT/DEVELOPMENT_LOCAL，而.env.test、.env.test.local中的值保持ENV（未被加载）；
• NODE_ENV=test时，__DOTENV_LOCAL的结果是TEST而非.env.local中的LOCAL，证明test环境下.env.local确实被跳过，环境专属的.env.test.local生效；
• NODE_ENV为undefined时，只有.env中的通用值ENV被加载。

已有环境变量不会被覆盖

测试在beforeEach中预设process.env.__DOTENV_PRESET = 'PRESET'（test/plugin.test.js），且各快照中__DOTENV_PRESET始终为PRESET，验证了 dotenv 的"不覆盖已存在变量"行为：预先在 shell 或系统层面设置的环境变量优先级高于任何.env文件。

五、变量展开：dotenv-expand 的工作原理

.env文件支持引用其他变量：

SNOWPACK_PUBLIC_API_URL=https://api.example.com SNOWPACK_PUBLIC_FULL_URL=${SNOWPACK_PUBLIC_API_URL}/v1

开启expand: true时，dotenv-expand会把SNOWPACK_PUBLIC_FULL_URL展开为https://api.example.com/v1。

测试快照清晰展示了展开与否的差异：测试夹具的.env中写有__DOTENV_EXPAND=${__DOTENV_PRESET}，而__DOTENV_PRESET被预设为PRESET——

• expand: true（默认）时，快照中__DOTENV_EXPAND的值为PRESET；
• expand: false时，快照中__DOTENV_EXPAND保持字面量\${__DOTENV_PRESET}，未被替换。

插件在加载完每个文件后执行展开（plugin.js）：

if (expand) require('dotenv-expand')(dotenv);

如果你的.env中刻意包含${...}字面文本、不希望被解析，可显式设置expand: false。

六、底层执行流程与测试驱动

插件初始化即加载

从源码结构看，@snowpack/plugin-dotenv是一个"配置阶段副作用"型插件：模块导出的工厂函数在 Snowpack 初始化配置时立即执行文件遍历与变量注入，返回的插件对象仅含name: '@snowpack/plugin-dotenv'标识（plugin.js），不参与构建阶段的资源转换。因此它的加载时机早于任何模块编译，变量一旦写入process.env，即可被核心的SNOWPACK_PUBLIC_过滤逻辑捕获。

完整的加载链路

1. Snowpack 读取snowpack.config.mjs，调用插件工厂函数；
2. 读取process.env.NODE_ENV，确定本次运行环境；
3. 按优先级构造.env.${NODE_ENV}.local→.env.local→.env.${NODE_ENV}→.env文件列表；
4. 对每个存在的文件调用dotenv.config({path})注入process.env；
5. 若expand开启，对每次注入结果调用dotenv-expand；
6. 构建/开发阶段，核心通过PUBLIC_ENV_REGEX过滤出SNOWPACK_PUBLIC_*变量，注入import.meta.env，并在 HTML 中替换%SNOWPACK_PUBLIC_*%、%PUBLIC_URL%、%MODE%占位符。

测试如何验证

测试通过独立的 execPlugin.js 子进程在隔离环境中执行插件，再收集__DOTENV_*开头的变量输出快照比对，覆盖了NODE_ENV的四种取值（undefined、development、test、production）与dir、expand的各种组合（test/plugin.test.js）。这种"隔离子进程 + 快照断言"的方式保证了测试不受宿主机环境变量污染。

七、插件版本演进

CHANGELOG.md 记录了插件的主要演进：

• 2.1.0：新增插件选项支持（dir/expand），并更新了文档链接；
• 2.2.0：新增expand选项，允许禁用dotenv-expand功能，适配包含${...}字面文本的场景。

更早的发布历史可查阅仓库的提交记录。需要说明的是，上述 CHANGELOG 中提到的外部讨论/提交链接属于 GitHub 资源，此处不再赘述。

八、与 Snowpack 环境变量体系配合使用

将plugin-dotenv与 Snowpack 核心能力串联起来，可以构建完整的配置流程：

1. 写入：.env中只放以SNOWPACK_PUBLIC_开头的"公开"变量；服务端私有密钥不要放进会被下发到浏览器的.env，或确保它们不带有该前缀（核心过滤会拦截）；
2. 读取：应用代码统一通过import.meta.env读取，支持解构写法const {SNOWPACK_PUBLIC_API_URL} = import.meta.env；判断开发/生产环境使用import.meta.env.MODE（snowpack dev时为development，snowpack build时为production）而非process.env.NODE_ENV；
3. 注意时机：这些变量在构建时静态注入，而非运行时动态读取，因此修改.env后需要重启snowpack dev或重新snowpack build才能生效；
4. 目录管理：文件较多时用dir选项统一收纳；需要${VAR}展开时保持默认expand: true，否则显式关闭。

结语

@snowpack/plugin-dotenv以极小的体积（仅依赖dotenv与dotenv-expand两个库）为 Snowpack 项目补齐了.env文件工作流：分层加载规则对齐了社区习惯，SNOWPACK_PUBLIC_前缀加核心正则过滤杜绝了密钥泄露，dir/expand两个选项覆盖了常见定制诉求。结合 plugin.js、plugin.test.js 与快照文件，你可以完全掌握其加载顺序与边界行为，在自己的项目中放心使用。

• 前端
• 开发工具
• 前端构建