
本文详解在 HTML + JS 前端项目中,不可直接暴露敏感密钥(如 API Token)给浏览器的前提下,如何通过构建工具(Webpack/Vite/React 等)安全注入非敏感环境变量,以及为何 process.env.Token 在纯 HTML 引入的脚本中必然失效,并提供生产就绪的替代方案。
本文详解在 html + js 前端项目中,**不可直接暴露敏感密钥(如 api token)给浏览器**的前提下,如何通过构建工具(webpack/vite/react 等)安全注入非敏感环境变量,以及为何 `process.env.token` 在纯 html 引入的脚本中必然失效,并提供生产就绪的替代方案。
在您的代码中,process.env.Token 试图在浏览器环境中读取 Node.js 风格的环境变量——这是根本不可行的。原因很明确:process 是 Node.js 运行时提供的全局对象,而浏览器中既无 process 对象,也无法访问服务器 .env 文件。即使您已配置 dotenv-webpack 插件,它仅在 Webpack 构建阶段将 .env 中的变量静态注入到打包后的 JavaScript 字面量中,但前提是:
✅ 您的 JS 必须作为模块被 Webpack 编译(如通过 entry: './src/applicant.js');
❌ 而您当前直接通过 <script src="../../applicant.js"></script> 引入未编译的原始 JS 文件——此时 Webpack 完全不参与处理,process.env.Token 将抛出 ReferenceError。
✅ 正确做法一:使用构建工具注入(推荐用于 SPA 或需打包的场景)
以您已配置的 Webpack 为例,需确保两点:
-
.env文件变量必须显式白名单化(dotenv-webpack默认不注入所有变量):# .env 文件(位于项目根目录) TOKEN=your_sumsub_token_here # 注意:此值若为敏感密钥,绝对不可注入!
-
修改 Webpack 配置,启用变量注入并重命名(避免混淆):
// webpack.config.js const Dotenv = require('dotenv-webpack'); module.exports = { // ...其他配置 plugins: [ new Dotenv({ safe: true, // 加载 .env.example 进行校验 systemvars: true, // 允许覆盖系统环境变量 defaults: false, // ⚠️ 关键:仅注入明确允许的变量,且建议用前缀隔离 allowEmptyValues: true, // 自定义变量映射(更安全、语义清晰) dotenvOptions: { path: './.env', }, // 显式指定要注入的变量名(必须与 .env 中一致) // 注入后,在代码中可直接使用 `process.env.TOKEN` }) ] }; -
在 JS 中安全使用(注意类型与默认值):
立即学习“Java免费学习笔记(深入)”;
dotenvx 安全环境变量管理器和加密器下载dotenvx 是由 dotenv 的创建者推出的_secure、跨平台环境变量管理器。它提供加密的 .env 文件、多环境支持,并通过其 CLI 运行器与任何编程语言或框架配合使用。
// src/applicant.js(必须从此入口被 Webpack 打包) document.getElementById('getstarted').addEventListener('click', () => { const applicantUrl = 'https://api.sumsub.com/resources/applicants'; // ✅ 安全前提:TOKEN 仅为公开标识符(如 client_id),绝非 secret/token! const token = process.env.TOKEN || 'fallback-token'; const applicantOptions = { method: 'POST', headers: { 'content-type': 'application/json', 'X-App-Token': token // ← 此处已替换为字符串字面量 }, body: JSON.stringify({ externalUserId: '1234EERF', email: 'user@example.com' }) }; fetch(applicantUrl, applicantOptions) .then(res => res.json()) .then(console.log) .catch(err => console.error('Fetch failed:', err)); });
⚠️ 严重安全警告:SumSub 的
X-App-Token是服务端凭证,一旦泄露,攻击者可完全冒充您的应用调用 SumSub API。绝不可通过前端 JS 直接发送! 正确方案是:
? 后端(Django/Node.js 等)提供一个/api/sumsub/applicant接口;
? 前端调用该接口(无需 Token);
? 后端在服务端添加X-App-Token头并转发请求至 SumSub。
这样敏感凭据始终留在服务器,符合最小权限原则。
✅ 正确做法二:纯静态 HTML 场景(无构建工具)
若项目极简(如仅 HTML + JS,无 Webpack/Vite),可采用「服务端模板注入」方式:
-
Django 模板中传递非敏感配置(安全):
<!-- base.html --> <script> // 安全:仅传递公开配置,如 API 基础路径、功能开关 const APP_CONFIG = { apiBase: "{{ API_BASE_URL }}", // 由 Django 视图传入 enableAnalytics: {{ ENABLE_ANALYTICS|lower }} // bool 转小写字符串 }; </script> <script src="{% static 'js/applicant.js' %}"></script> -
JS 中使用预置对象:
// applicant.js(纯客户端,无构建依赖) document.getElementById('getstarted').addEventListener('click', () => { fetch(`${APP_CONFIG.apiBase}/resources/applicants`, { /* ... */ }) });
❌ 绝对禁止的操作
- 将
.env文件置于 Web 可访问目录(如public/.env)→ 浏览器可直连下载; - 使用
fetch('/.env')读取 → 暴露全部密钥; - 在
<script></script>标签内硬编码const TOKEN = "xxx"→ DevTools 一眼可见。
总结:安全三原则
| 原则 | 说明 |
|---|---|
| ① 敏感数据永不离服务端 | API keys、secrets、JWT signing keys 等必须由后端持有并代理请求。 |
| ② 前端变量仅限非敏感上下文 | 如 REACT_APP_API_URL、VITE_APP_ENV、NUXT_PUBLIC_BASE_URL —— 仅用于配置路由、开关、文案等。 |
| ③ 构建时注入,运行时静态化 | Vite 的 define、Webpack 的 DefinePlugin、CRA 的 REACT_APP_* 均在打包阶段将变量替换为字符串,不依赖运行时解析。 |
遵循以上方案,您既能实现环境配置的灵活管理,又能彻底规避密钥泄露风险。记住:前端没有秘密,安全始于服务端。

















