
本文详解在纯 HTML + JS 项目中,如何安全地将 .env 文件中的非敏感配置注入客户端脚本,重点规避直接暴露密钥的风险,并对比 Webpack、Vite、React 等主流方案的适用边界与最佳实践。
本文详解在纯 html + js 项目中,如何安全地将 `.env` 文件中的非敏感配置注入客户端脚本,重点规避直接暴露密钥的风险,并对比 webpack、vite、react 等主流方案的适用边界与最佳实践。
在前端 JavaScript 中直接使用 process.env.Token(如你代码中所示)无法生效——因为浏览器环境没有 Node.js 的 process 对象,process.env 是服务端或构建时概念,客户端运行时根本不存在该全局变量。更关键的是:任何硬编码或通过构建工具“注入”到前端代码中的密钥(如 X-App-Token),一旦进入浏览器,即等同于公开。这违反了基本安全原则:服务端密钥绝不应出现在客户端可读代码中。
因此,解决该问题必须区分两类场景:
✅ 场景一:变量为「非敏感配置」(推荐前端注入)
例如 API 基础路径、功能开关、应用版本号等可公开信息。此时可借助构建工具安全注入:
-
Webpack + dotenv-webpack 插件(你已配置)
你当前的webpack.config.js已启用Dotenv(),但需注意:-
dotenv-webpack默认仅注入process.env.*到模块作用域,不自动挂载到全局window; - 你的
applicant.js是直接通过<script src></script>引入的未打包裸文件,Webpack 配置对其完全无效(Webpack 只处理entry指定的入口文件并生成bundle.js)。
✅ 正确做法:
dotenvx 安全环境变量管理器和加密器下载dotenvx 是由 dotenv 的创建者推出的_secure、跨平台环境变量管理器。它提供加密的 .env 文件、多环境支持,并通过其 CLI 运行器与任何编程语言或框架配合使用。
- 将
applicant.js改为 Webpack 入口,构建后引入dist/bundle.js; - 在 JS 中直接使用
process.env.Token(Webpack 会将其替换为字符串字面量); -
但前提是
.env中的Token必须是非敏感值(如测试用公钥),否则仍危险。
// .env(仅限非敏感值!) TOKEN=public-test-token-abc123 // applicant.js(Webpack 构建后,process.env.TOKEN → "public-test-token-abc123") const token = process.env.TOKEN; // ✅ 安全(若值本身可公开)
-
-
Vite(更简洁)
Vite 原生支持.env,且仅暴露VITE_开头变量:# .env VITE_API_BASE_URL=https://api.sumsub.com # TOKEN 不以 VITE_ 开头 → ❌ 不会被注入!
// 直接在 JS 中使用(构建时替换,无 runtime 依赖) fetch(`${import.meta.env.VITE_API_BASE_URL}/resources/applicants`, { headers: { 'X-App-Token': import.meta.env.VITE_PUBLIC_TOKEN } // ✅ 仅当此 token 允许公开 });
⚠️ 场景二:变量为「敏感密钥」(必须服务端代理)
你示例中的 X-App-Token 极大概率是 SumSub 的私有 API Token,绝不可暴露给前端。正确架构应为:
Browser → Your Backend (e.g., Django/Express) → SumSub API
- 前端只调用你自己的
/api/applicant接口; - 后端从
.env读取SUMSUB_TOKEN,拼装完整请求并转发; - 前端 JS 完全不接触任何密钥。
// applicant.js(安全版)
document.getElementById('getstarted').addEventListener('click', () => {
// 调用你自己的后端接口,而非 SumSub 直连
fetch('/api/applicant', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ externalUserId: '1234EERF', email: 'user@example.com' })
})
.then(r => r.json())
.then(console.log)
.catch(console.error);
});
# Django views.py(服务端代理)
from django.http import JsonResponse
from django.views.decorators.csrf import csrf_exempt
import requests
import os
@csrf_exempt
def create_applicant(request):
if request.method == 'POST':
data = json.loads(request.body)
# ✅ 服务端安全读取密钥
token = os.getenv('SUMSUB_TOKEN')
response = requests.post(
'https://api.sumsub.com/resources/applicants',
json=data,
headers={
'Content-Type': 'application/json',
'X-App-Token': token
}
)
return JsonResponse(response.json(), status=response.status_code)
? 关键总结与注意事项
-
永远不要在前端代码中存放真实 API 密钥:
process.env.Token在浏览器中是undefined,即使 Webpack 注入也等于公开密钥; -
.env文件仅对构建工具/服务端有效:纯静态 HTML 引入的 JS 无法访问它,必须通过构建流程(Webpack/Vite)或服务端渲染(Django 模板)传递; -
若必须前端配置,请严格区分敏感性:
- ✅ 允许:
VITE_API_URL,REACT_APP_FEATURE_FLAG(Vite/React CRA); - ❌ 禁止:
VITE_SUMSUB_TOKEN,REACT_APP_DB_PASSWORD;
- ✅ 允许:
-
生产环境务必验证:构建后检查
bundle.js源码,确认敏感值未被意外写入; - 替代方案:对高安全要求场景,使用 OAuth 令牌交换、短期 JWT 或后端签发临时凭证,彻底避免前端持有长期密钥。
安全不是功能,而是架构基石——让密钥留在服务器,让前端只做它该做的事。
Java免费学习笔记:立即使用
解锁 Java 大师之旅:从入门到精通的终极指南










