一句话结论:前端没有秘密,写进前端的东西一律按「已公开」对待。 所以前端要解决的不是「怎么把密钥藏好」,而是「怎么让前端根本不需要密钥」。密码同理——只要加密用的 key 跟代码一起发布,这层加密就只是把明文换成了「钥匙挂在门上」的密文。本文按「分类 → 判据 → 方案 → 顺序 → 门禁」展开,密码和密钥分开讲,最后拿一个真实项目的 21 处命中做归类,只取 OWASP、Vite、Stripe、高德、GitHub 官方文档与 npm 信息。
一、一次「看起来合规」的登录
某 SaaS 前端要过安全评审,评审项里有一条:密码不得明文传输。
最省事的落地方式是:登录前用 SM4 把密码加密,请求体里放密文。评审看到抓包里没有明文,过了;测试看接口通了,过了;演示时一切正常。这一层就这样活了两年多。
直到有人问了三个问题:
- 加密用的 key 从哪来?
- 这个 key 跟着谁一起发到了浏览器?
- 拿到 key 的人能做什么?
三个问题的答案分别是「源码里的一个常量」「跟业务代码同一个 js 包」「能离线还原任何一个抓到的密码」。于是这层加密的实际效果只剩下一个:让人以为已经处理过了。
更麻烦的是它的连带损失——服务端日志、网关日志、监控 SDK 采集到的请求体,全是密文。这看起来比明文「安全」,但它给了团队一个错觉:日志里没有明文,所以不用脱敏。等到 key 泄漏,这些日志就变成了明文密码的存档。
| 拿到这个 key 的人 | 能做什么 | 代价 |
|---|---|---|
| 任意访客(打开 F12 就行) | 解出自己抓到的任何一次登录密码 | 零成本 |
| 能看网关日志的人 | 批量还原历史密码 | 一次 grep |
| 拿到一张弱口令密文表的人 | 不解密也能识别哪些账号用了弱口令 | 见第五章 ECB 部分 |
先把结论摆在这里,后面逐条论证:密码不该在浏览器里做对称加密,密钥不该放进任何会发给浏览器的文件。
二、密码和密钥不是一回事
很多讨论一开口就乱,是因为把两样东西混成了一件。它们的处置方式完全不同。
| 对象 | 是什么 | 前端能做的 | 前端绝不能做的 | 正确位置 |
|---|---|---|---|---|
| 用户密码 | 用户脑子里的凭据 | 采集、经 TLS 传输 | 对称加密、哈希、缓存、打印 | 服务端存哈希(Argon2id / bcrypt) |
| 应用密钥 | 系统对系统的凭据 | 什么都不做 | 出现在任何会发给浏览器的字节里 | 服务端运行时环境变量或密钥库 |
| 会话令牌 | 短期身份凭据 | 存储、随请求携带 | 长期明文存 localStorage | HttpOnly Cookie 优先 |
| 可公开标识 | 设计上就公开的 id | 正常使用 | 无限制地裸奔 | 配好域名限制与配额 |
这张表能解释两类最常见的错:
- 把令牌当密钥藏。 前端拿到 token 就必然能被读走,加密存储只会让「读」多一步。真正要控制的是它的生命周期与作用域,不是它存得够不够隐蔽。
- 把密钥当令牌用。 密钥泄漏后换一次就行——这个思路没错,但很多项目连「换」这一步都没有,因为它压根不在台账上,没人知道它的存在。
三、前端没有秘密:四条证据
在动手改之前,先接受一个事实:只要是浏览器执行过的代码,就等于公开源码。四条证据,每条都能自己验。
第一条:构建产物就是源码。 压缩只改名字,不改字符串字面量。密钥是字符串,所以它在产物里原样躺着。
第二条:VITE_ 前缀不是保密开关。 它恰恰是「注入客户端」的开关。Vite 官方文档的原话是:VITE_* 变量不应包含 API key 这类敏感信息。反过来验一次最直观——不带前缀的变量在浏览器里是 undefined,带前缀的才拿得到值。也就是说,前缀决定它会不会进包,而不是决定谁能看见。
// 反例:以为加前缀等于「只在服务端可见」
const secret = import.meta.env.VITE_API_SECRET; // 值被原样写进 js 产物
// 没有前缀的变量在浏览器里永远是 undefined,这才是 Vite 的隔离机制
// 正例:允许出现在前端的,只能是「本来就是公开的」那类
const mapKey = import.meta.env.VITE_AMAP_JS_KEY; // 仍需配域名白名单与配额
第三条:运行时配置文件一样能下载。 有些项目为了「不打进包」,把配置抽成 _app.config.js,运行时再 fetch 回来。但这仍然是一个静态文件——任何人访问 /config.js 都能拿到。抽出去只是把「在 bundle 里搜」变成「在 Network 面板里看」。
第四条:git 历史比源码更长寿。 删掉一行代码不等于删掉这条记录。四行命令就能完成取证:
# 1) 产物里搜已知的密钥前缀(先扫已经暴露的)
grep -rnoE "sk_live_[A-Za-z0-9]{10}|sm4key|aesKey" dist | head
# 2) 按变量名扫源码(找同类,不只找这一个)
grep -rnE "(apiKey|secret|password|salt|iv)\s*[:=]\s*['\"][^'\"]{8,}" src | head -30
# 3) 按值形态扫(32/40 位十六进制串是国密与云厂商 key 的常见形态)
grep -rnoE "\b[0-9a-f]{32}\b" src | head
# 4) 回溯历史:这个密钥是什么时候进来的
git log --all -S "<密钥前缀>" --oneline
第 4 条最有价值。它回答的不是「谁写错了」,而是「哪一次搬迁、哪一个模板、哪一次赶工带进来的」——这决定了你要修的是一个文件,还是一类习惯。
四、一条判据:三问定生死
判断一个凭据能不能放前端,只用三个问题,全部满足才算合格。
| 问题 | 不满足意味着 |
|---|---|
| 拿到它的人,能不能做出超出该用户权限的事? | 能,就是提权入口,不能放 |
| 能不能把使用范围限制在指定域名 / IP / 包名? | 不能,任何网站都能拿去刷,不该放 |
| 有没有时效或额度,出事能不能快速吊销? | 都没有,泄漏就是永久损失,绝不放 |
按这三问过一遍常见凭据,结论很干脆:
| 凭据 | 能放前端吗 | 一句话依据 |
|---|---|---|
Stripe pk_live_ | 可以 | 官方标注 Safe to expose: Yes,只能建 token,不能扣款 |
Stripe sk_ / rk_ | 不可以 | 官方标注 No,sk_ 拥有全部权限 |
| 地图 JS SDK key | 有条件可以 | 必须配 Referer 白名单 + API 限制 + 日配额 |
| 地图「Web 服务」key | 不可以 | 服务端型 key,能直连 REST 接口按量计费 |
| 云厂商 AccessKey | 不可以 | 长期凭据,泄漏等于账号被接管 |
| 对称加密 key(SM4 / AES) | 不可以 | 它的安全性完全等于「没人拿到它」 |
| OAuth Client ID / Secret | 前者可以 / 后者不行 | Secret 可冒充应用换 token,公共客户端应改 PKCE |
再补一条容易被忽略的:可公开不等于可以硬编码。 可公开的 key 也应该走配置注入、按环境区分、可一键吊销。因为它虽然不泄漏数据,但能被别人拿去刷你的账单——你依然需要一个止损开关。
顺带说一句合规口径。OWASP Top 10:2025 把这类问题归在 A02:2025 Security Misconfiguration(2021 年第 5 位升到第 2 位),弱点编号 CWE-798 Use of Hard-coded Credentials,官方标注利用可能性为 High,并专门点出「出站型」变体:前端去连后端时,把后端凭据直接写进了前端产物。OWASP 给的处理方式写得很直接——用身份联邦、短期凭证或平台 RBAC,替代在代码、配置、流水线里嵌静态密钥。这句就是全文的靶心。
五、密码怎么处理
这一章是核心。四条路线,先把结论列出来,再解释为什么只剩一条。
5.1 四条路线的对比
| 路线 | 做法 | 机密性 | 抗重放 | 结论 |
|---|---|---|---|---|
| 前端对称加密 | SM4 / AES 加密密码,key 写在源码 | 无(key 同包) | 无(密文可重放) | 不可用 |
| 前端哈希 | SHA256 / SM3 算摘要再发 | 无(摘要即密码) | 无 | 更糟,见 5.3 |
| 前端非对称加密 | SM2 / RSA 公钥加密,私钥在服务端 | 有 | 需配 nonce | 合规要求时可接受 |
| HTTPS 直传 + 服务端哈希 | 前端不碰密码,服务端存 Argon2id | 有(TLS) | 靠会话与风控 | 推荐 |
5.2 为什么前端对称加密的机密性是零
两个原因,一个是设计上的,一个是算法模式上的。
设计上的:key 和密文同路。 加密发生在浏览器,解密发生在服务端,那么浏览器必须持有加密能力所需的 key。这个 key 就在 js 里。攻击者不需要「破解加密」,他只需要「打开产物、搜一下、复制」。密码学的强度完全没有被使用——被绕过的从来不是算法,是密钥分发。
算法模式上的:默认 ECB 会放大伤害。 前端常用的国密库在调用时如果没传 iv,默认走 ECB 模式(sm-crypto 的源码注释里明确写着「CBC 模式,默认走 ECB 模式」)。ECB 是分组独立加密,同样的明文块永远得到同样的密文块,于是:
- 同一个密码在不同账号、不同时间加密出来完全相同——攻击者不需要解密,只要有一张「常见弱口令 → 密文」对照表,就能在数据层面批量识别谁用了弱口令;
- 密码不足一个分组时要按 pkcs#7 补齐,补齐字节数是确定的(8 位密码固定补 8 个
08),连填充后的分组都一致,对照表的构造成本进一步降低。
怎么验自己有没有踩: 用同一个密码连打两次登录,比较请求体里的密文。两次相同 → ECB;两次不同 → 至少用了随机 IV 或非对称。这一步 30 秒能做完,比读代码快。
5.3 为什么「前端哈希」比加密更糟
有人会说:那把密码哈希一下再发,服务端存哈希比对,不就谁也拿不到明文了?
这条路更危险,因为它把哈希值本身变成了密码:
- 如果服务端比对的是「前端算出来的摘要」,那攻击者抓到摘要就能直接登录——他不需要知道原密码。这就是 pass-the-hash:凭据从「你知道什么」退化成了「你抓到什么」。
- 如果摘要不加盐,彩虹表直接命中常见密码;如果加盐,盐必须在前端,而盐也在包里,等于没加。
- 前端哈希还会让服务端失去做密码强度校验、复用检测、风控画像的能力——它拿到的是一个摘要,看不出任何密码特征。
一条能记住的判据: 如果验证端需要的只是「客户端算出来的那个值」本身,那这个值就是密码。凡是能被原样重放的,都不是加密,是换了个编码。
5.4 推荐路线:HTTPS 直传,服务端存哈希
HTTPS 已经提供了传输层加密,前端再加一层对称加密不增加任何安全性,只增加一处泄漏点。正确的位置在服务端。
// 前端:不做任何加密,原样交给 TLS
import { http } from '@/utils/http';
export function login(username: string, password: string, captcha: string) {
return http.post('/api/auth/login', { username, password, captcha });
}
// 服务端:只存哈希,登录时比对(示意,Node + argon2)
import argon2 from 'argon2';
// OWASP 密码存储备忘单给出的参考配置之一:Argon2id
const OPTS = { type: argon2.argon2id, memoryCost: 19456, timeCost: 2, parallelism: 1 };
// 注册 / 改密时
const passwordHash = await argon2.hash(plain, OPTS);
// 登录时:verify 内部做常数时间比较,不要自己写 ===
const ok = await argon2.verify(user.passwordHash, plain);
配套的三件事,缺一件这层就不成立:
- 全站强制 HTTPS,并开 HSTS。传输层是这条路线唯一的机密性来源。
- 密码重置与改密走同一套哈希,不要在某个分支里图省事存明文或 MD5。
- 登录失败不做「用户是否存在」的区分,错误信息统一,避免账号枚举——这跟前端加密没关系,但总被一起做错。
还有一个常见的误区:上前端加密是为了「防暴力破解」。不成立。防自动化靠的是验证码、频控、设备指纹、异常登录检测,这些都在服务端。前端加密挡不住脚本,脚本比你更会调你的加密函数。
5.5 合规必须国密时:SM2 公钥 + nonce
有些场景确实有硬性要求:「密码传输必须用国密算法」。这时不该回到对称加密,而应换成非对称——公钥放前端是安全的,这是非对称加密的设计前提。
// 前端:只用公钥加密,私钥永远在服务端
import { sm2 } from 'sm-crypto';
// 公钥可以公开,它只能加密,不能解密
const SM2_PUBLIC_KEY = import.meta.env.VITE_SM2_PUBLIC_KEY as string;
export async function buildCredential(plain: string) {
// 一次性 nonce + 时间戳由服务端下发,二者一并加密
const { nonce, ts } = await http.get('/api/auth/nonce');
// 第三个参数 1 表示 C1C3C2 排列,必须与服务端约定一致
return { cipher: sm2.doEncrypt(`${plain}|${nonce}|${ts}`, SM2_PUBLIC_KEY, 1), nonce };
}
服务端要做三件事才算真的防住重放:校验 nonce 未被使用过、时间戳在 5 分钟窗口内、同一 nonce 只用一次。少了这三条,公钥加密只解决了「不被离线解密」,解决不了「抓到密文重放一次也能登录」。这是国密改造里最常漏的一环。
顺带提醒:SM2 加密同一明文每次结果不同(有随机数),所以 5.2 里那个「两次密文相同就是 ECB」的自检,在这一路线下也顺便通过了。
5.6 密码在链路上还有六个泄漏点
密码这条数据最难的地方在于:它不只出现在登录接口。下面六处,只要漏一处,前面所有努力都白做。
| 位置 | 典型形态 | 处置 |
|---|---|---|
| 控制台日志 | console.log('params', params) | 生产构建剔除;用 import.meta.env.DEV 包住 |
| 请求 URL | 把密码拼进 query | 只走请求体,永不放 URL |
| 监控 SDK 请求采集 | 自动上报 URL 与 body | 上报前统一脱敏,见下方代码 |
| 本地存储 | 「记住密码」写进 localStorage | 不存;要记住就存脱敏后的账号名 |
| 异常上报与录屏 | 报错堆栈里带上了表单值 | 采集侧白名单字段,输入框默认掩码 |
| 网关与代理日志 | 全量 body 落盘 | 按字段脱敏后再落,保留期设短 |
监控 SDK 那条最容易被忽略,因为它默认就在工作:
// 上报前统一脱敏:不要指望「我不会打印它」,要指望「打印了也发不出去」
const SENSITIVE = /pass(word)?|pwd|token|secret|otp|captcha|idcard|phone/i;
function scrub(input: unknown, depth = 0): unknown {
if (depth > 4 || input == null) return input;
if (Array.isArray(input)) return input.map((v) => scrub(v, depth + 1));
if (typeof input !== 'object') return input;
return Object.fromEntries(
Object.entries(input as Record<string, unknown>).map(([k, v]) =>
SENSITIVE.test(k) ? [k, '***'] : [k, scrub(v, depth + 1)],
),
);
}
怎么验: 打开生产站点,登录一次,然后去监控平台搜这次会话。请求体里的 password 字段应该是 ***。如果是明文,或者是一串能被你解开的密文,这条就是 P0。
六、密钥怎么处理:五种方案
方案按「侵入性」从低到高排,实际项目通常是组合使用。判断标准只有一条:这个 key 有没有必要出现在浏览器里。
6.1 方案一:干脆不要它(能力下沉)
最彻底的方案是让前端根本不需要这个能力:静态图由服务端生成并返回图片、短信与邮件由服务端发起、文件上传用服务端预签名的 URL 而不是长期 AccessKey、数据聚合在服务端做完只吐结果。
代价是要后端配合加接口;收益是这类风险永久消失,而不是「暂时藏好了」。凡是能这么做的,优先这么做。
6.2 方案二:BFF / 网关代理(最通用)
在浏览器和第三方之间加一层自己的服务,凭据留在服务端。改前是「浏览器带着 key 直连第三方」,改后是「浏览器带着用户会话连自己的 BFF,BFF 带上 key 转发」。
// bff.mjs —— 三件事:校验会话、路径白名单、按用户限流
import { createServer } from 'node:http';
const UPSTREAM = 'https://api.vendor.example.com';
const KEY = process.env.VENDOR_API_KEY; // 只存在于服务端运行时
const ALLOWED = ['/v1/search', '/v1/translate'];
const buckets = new Map();
function allow(userId) {
const now = Date.now();
const b = buckets.get(userId) || { tokens: 30, ts: now };
b.tokens = Math.min(30, b.tokens + ((now - b.ts) / 1000) * 0.5); // 0.5 qps 回填
b.ts = now;
if (b.tokens < 1) return buckets.set(userId, b), false;
b.tokens -= 1;
buckets.set(userId, b);
return true;
}
createServer(async (req, res) => {
const userId = req.headers['x-user-id']; // 换成校验自己签发的会话
if (!userId) return res.writeHead(401).end('unauthorized');
if (!ALLOWED.includes(req.url)) return res.writeHead(404).end('not found');
if (!allow(userId)) return res.writeHead(429).end('too many requests');
const upstream = await fetch(UPSTREAM + req.url, {
method: req.method,
// 只注入自己的凭据,绝不转发客户端传来的认证头
headers: { authorization: 'Bearer ' + KEY, 'content-type': 'application/json' },
body: ['GET', 'HEAD'].includes(req.method) ? undefined : req,
duplex: 'half',
});
res.writeHead(upstream.status, { 'content-type': 'application/json' });
res.end(Buffer.from(await upstream.arrayBuffer()));
}).listen(8787);
四个必须做的点,缺一条这层就白加:路径白名单(否则变成开放代理,攻击者拿你的 key 随便刷)、按用户限流(否则换个方式刷你的 BFF)、不转发客户端的认证头、不把上游错误原样透传(错误体里可能带上游 key 片段或内网地址)。
6.3 方案三:短期凭证(前端确实要直连时)
对象存储直传、设备通道这类场景绕不开直连,那就换成「有效期很短、权限很窄、可随时吊销」的临时凭据。
// 前端:先换凭证,再用它直连;长期密钥从不出现在浏览器
type Sts = { accessKeyId: string; accessKeySecret: string; securityToken: string; expiresIn: number };
async function upload(file: File) {
const sts = await http.post<Sts>('/api/sts/upload', { scene: 'avatar' }); // 权限只含本目录 PUT
const form = new FormData();
form.append('OSSAccessKeyId', sts.accessKeyId);
form.append('security-token', sts.securityToken);
form.append('key', `avatar/${userId}/${Date.now()}.png`);
form.append('file', file);
// 直传对象存储;凭证 15 分钟过期,权限仅限 avatar/ 前缀
return fetch(OSS_HOST, { method: 'POST', body: form });
}
同一个思路解决过我见过的一类典型问题:设备通道的账号口令写在构建配置里,用户名和口令还完全相同,两个都原样进了产物。真正的风险不是「能不能连上」,而是「连上之后能订阅什么」——如果 broker 的 ACL 按用户名一刀切授权,任何拿到口令的人都能订阅全平台设备状态。正确做法是登录后换取一次性凭据,并且 broker 的 ACL 按主题前缀授权(例如只允许 tenant/{tenantId}/#)。
6.4 方案四:受限的可公开 key(第三方只给 key 时)
有些第三方只提供 key 这一种接入方式(地图、部分统计与推送服务)。这时该做的不是藏,而是把「可被滥用的范围」压到最小。以地图 key 为例,四层一起上才算合格:
| 层 | 动作 | 验收 |
|---|---|---|
| 应用限制 | 配 HTTP Referer 白名单 / IP 白名单 / 应用包名 | 非白名单域名调用返回域名不合法 |
| API 限制 | 只勾选实际用到的接口 | 未勾选接口调用被拒 |
| 配额 | 设日调用上限 | 超限返回配额错误,而不是继续计费 |
| 账单告警 | 设消费阈值告警 | 阈值触发能收到通知 |
还要分清 JS API key 与 Web 服务 key:前者给浏览器用,靠域名限制收敛;后者是服务端型凭据,能直连 REST 按量计费,不能出现在前端。这两类混在一个配置文件里,是很多项目的通病——审计时只要一个 key 泄漏,往往意味着同一份配置里的其他 key 也一起暴露了。
6.5 方案五:边缘函数
没有自有服务器、又不想为一个转发接口新开服务时,用边缘函数(Cloudflare Workers、各云厂商的边缘运行时)做同一件事:请求到边缘,注入密钥,转发出去。它比 BFF 轻,但要额外注意两件事:密钥存在平台的环境变量里并开启加密存储;边缘侧同样要有限流,否则清理成本会转移成账单。
6.6 选型表
| 场景 | 建议方案 | 一句话理由 |
|---|---|---|
| 能改成服务端做的能力 | 方案一 能力下沉 | 风险永久消失,不用长期维护 |
| 第三方 REST 接口(搜索、翻译、AI) | 方案二 BFF / 网关 | 最通用,凭据只在服务端,可加限流与审计 |
| 对象存储直传、设备通道 | 方案三 短期凭证 | 直连不可避免时,用短 TTL 换安全边界 |
| 地图、统计等前端 SDK | 方案四 受限 key | 第三方只给 key,只能靠限制与配额收敛 |
| 无自有服务端的小项目 | 方案五 边缘函数 | 成本最低的转发方案 |
| 数据库连接串、JWT 签名密钥、支付 secret | 一律不下前端 | 没有任何「限制」能兜住这一类 |
七、21 处命中:七类归因
一个 Vue 3 + Vite 的中后台 SaaS 前端,2700 多次提交,2300 多个源码文件,按「变量名 + 值形态」双向扫,命中 21 处。按类型归成七组,加起来正好 21 条。
| 类型 | 处数 | 典型形态 | 为什么能活这么久 | 处置 |
|---|---|---|---|---|
| 对称加密密钥 | 2 | 登录密码的 SM4 key、本地存储的 AES key 与 IV | 从旧项目整体搬迁时一起复制过来 | 删常量 + 改协议 |
| 通道凭据 | 1 | 设备通道账号口令写在构建配置 | 「上线只要通就行」 | 短期凭据 + ACL 收窄 |
| 第三方 key | 4 | 地图 JS key、Web 服务 key、安全密钥、演示页 key | 没有「key 分类」这个概念 | 限制 + 分离 + 删死配置 |
| 测试凭据 | 3 | .env 明文口令、历史文档里的同一口令、mock 固定 token | 只忽略了 .env.local,没忽略 .env | 先轮换,再谈清理 |
| 内网与拓扑 | 5 | 内网 IP、开发代理目标、注释里的预签名 URL、内网仓库地址 | 被当成「不算密钥」 | 移出源码 + 改占位符 |
| 构建期泄漏 | 3 | Dockerfile 注入口令、生产环境打印配置、不生效的 drop_console | 以为「配置了就是生效了」 | 删打印 + 实现或删开关 |
| 工程门禁 | 3 | 提交钩子只有 lint、没有任何 CI、忽略规则不完整 | 靠人眼 review | 装三道门 |
三个观察比数字更有用:
第一,21 条里没有一条是「有人故意写错」。 全部是三种动作的副产品:搬迁(整体复制)、合规(形式化落地)、赶上线(先跑通再说)。这意味着只修代码不改动作,三个月后会有一批新的。
第二,P0 的位置有个共同特征:它是被很多地方调用的工具函数。 那处加密密钥被登录、改密、重置、校验、新建用户共 5 个调用点引用。反过来说,这也是好消息——改一个文件就能提升整个系统的水位。审计时优先找这种「被 5 处以上调用的加解密/签名工具」,性价比最高。
第三,那条最危险的配置从来没被用过。 构建配置里写着 VITE_DROP_CONSOLE = true,但构建工具里压根没有实现这个开关。于是 console.log('env >>>', config) 一直留在生产包里,每次页面加载都打印一份完整配置。这次打印的内容不敏感,但它是一条「以后谁往配置里加敏感项就自动泄漏」的通道。留着一个不生效的安全配置,比没有更危险,因为它会让人误以为已经处理过了。
八、改的顺序:先轮换,再改代码
顺序错了,改法再对也会出事。按下表从下往上做,每一步都能独立回滚。
| 步 | 对象 | 前置条件 | 回滚 |
|---|---|---|---|
| 6 | 密码协议切换(去掉前端加密,或改 SM2) | 服务端已能接受新格式 | 前端保留旧开关 |
| 5 | 对称密钥轮换 | 服务端同时支持新旧两套 | 回退到只认旧 key |
| 4 | 短期凭据接口上线 | 前后端联调通过 | 切回静态配置 |
| 3 | 通道口令轮换 | broker ACL 已改为按租户前缀授权 | broker 保留旧账号 24 小时 |
| 2 | 第三方 key 轮换 | 控制台已建新 key 并配好限制 | 旧 key 暂不删除 |
| 1 | 测试环境口令 | 已通知使用方 | 改回旧口令 |
四个坑,每一个都真实发生过:
- 先改代码后轮换。 代码改成从服务端取 key,服务端还认旧 key,中间会出现「老客户端能登、新客户端不能登」的混乱期。
- 只改一处。 那个加密密钥有 5 个调用点,漏一个就出现「登录正常、改密码失败」这种只在特定路径复现的问题。
- 轮换后不回查。 要查两件事:服务端日志里是否还有用旧 key 的请求(说明有客户端没更新)、第三方控制台的调用量是否异常(说明有人正在用你的 key)。
- 先清历史再轮换。
git filter-repo会重写所有提交哈希,全员必须重新克隆。在口令还没轮换时先清历史,等于什么都没解决,只是把证据藏起来了。顺序永远是:先轮换,后清理。
九、三道门:让那一行没有地方可写
止血是删掉那一行,防复发是让它「没有地方可写」。三道门按成本从低到高。
9.1 第一道:提交前(本地,零成本)
#!/bin/sh
# .husky/pre-commit
pnpm exec lint-staged
# 只扫暂存区,命中即阻断提交;误报写进 .gitleaks.toml 白名单
if command -v gitleaks >/dev/null 2>&1; then
gitleaks protect --staged --redact --verbose || {
echo "检测到疑似密钥,提交已阻断。"
exit 1
}
fi
9.2 第二道:CI(覆盖全仓与全历史)
# .gitlab-ci.yml 片段
secret-scan:
stage: test
image: zricethezav/gitleaks:latest
script:
- gitleaks detect --source . --redact --verbose --no-banner
allow_failure: false
除了通用规则,把本项目的高风险形态固化成自定义规则,命中率会明显提高:
# .gitleaks.toml —— 前端特有的形态,通用规则覆盖不到
[[rules]]
id = "frontend-symmetric-key"
description = "前端源码中的对称加密密钥"
regex = '''(?i)(sm4key|aeskey|cipheriv|secretkey)\s*[:=]\s*['"][0-9a-f]{32}['"]'''
tags = ["crypto", "frontend"]
[[rules]]
id = "map-web-service-key"
description = "服务端型地图 key 不应出现在前端"
regex = '''(?i)(webservice\w*key|serverkey)\s*[:=]\s*['"][0-9a-f]{32}['"]'''
tags = ["api-key"]
工具选型不用纠结:gitleaks 适合全历史与暂存区扫描,trufflehog 会实际验证凭据是否可用(适合 CI 卡口,误报少但慢),detect-secrets 适合先建基线、之后只报新增,secretlint 适合按项目规则接入。四个都是活跃维护的开源项目,装一个就比不装强。
9.3 第三道:上线前(扫产物,不看源码)
# 产物里不该出现的四类东西,期望全部零命中
grep -rniE "sk_live_|AKIA[0-9A-Z]{16}|sm4key|aesKey" dist
grep -rE "192\.168\.[0-9]+\.[0-9]+|10\.[0-9]+\.[0-9]+\.[0-9]+" dist
grep -c "env >>>" dist/assets/entry/*.js
ls dist/**/*.map 2>/dev/null # 生产是否发布了 sourcemap
再加两条人工验收:用非白名单域名调用一次地图接口,应该被拒;用匿名身份读一次别人的数据,应该失败。这两条的判据不是「key 藏好了没」,而是「拿着它能不能越权」。
十、上线前 12 条自查
| # | 一句话验收动作 |
|---|---|
| 01 | 同一密码连续登录两次,请求体密文不同(不是 ECB) |
| 02 | 抓包拿到的登录密文,重放一次应该被拒(nonce 生效) |
| 03 | 前端源码与产物里搜不到任何对称加密 key |
| 04 | 服务端存的是 Argon2id / bcrypt 哈希,不是明文或 MD5 |
| 05 | 登录请求体里的密码字段,在监控平台显示为 *** |
| 06 | 全站强制 HTTPS,HSTS 已开,HTTP 请求被 301 |
| 07 | 第三方 key 用非白名单域名调用被拒 |
| 08 | 服务端型 key(地图 Web 服务、支付 secret)在 src 与 dist 零命中 |
| 09 | 产物里无内网地址、无配置打印、未发布 sourcemap |
| 10 | 提交钩子能拦住一个故意写进 .env 的假密钥 |
| 11 | CI 全历史扫描为绿,且失败会阻断合并 |
| 12 | 每个生产 key 都有台账:用途、限制方式、轮换人、上次轮换日期 |
第 12 条最像流程、最不技术,但它决定了前三道门会不会在半年后变成摆设。
十一、小结
三句话收尾:
- 前端没有秘密。 判断一个东西能不能放前端,不要问「藏得够不够深」,要问「被别人拿去能干什么」。
- 密码不要在前端加工。 对称加密的 key 同路,哈希的摘要就是密码。要么 HTTPS 直传由服务端存哈希,要么用 SM2 公钥加 nonce——除此之外的第三条路都是自我安慰。
- 密钥要么别要,要么短期。 能下沉到服务端的下沉,不能的走 BFF 或短 TTL 凭证,剩下的才轮到「受限的可公开 key」,而且必须配齐域名限制、配额与账单告警。
这件事还有一层不太好听但真实的原因:硬编码密钥的危险不只在于「能被利用」,还在于「你无法证明它没被利用」。产物里躺了两年的 key,你不知道有没有人搜过。所以发现之后的第一动作永远是轮换,而不是先研究影响面——研究可以并行,轮换不能等。
你们项目里有没有那种「加了密但等于没加」的登录?或者某个 VITE_ 变量其实一直是公开的?评论区聊聊,我最想听的是第二种——它通常要等一次外部通报才会被发现。
参考资料:
- OWASP Top 10:2025 A02 Security Misconfiguration:top10.owasp.org/2025/A02_20…
- CWE-798 Use of Hard-coded Credentials:cwe.mitre.org/data/defini…
- OWASP 密码存储备忘单:cheatsheetseries.owasp.org/cheatsheets…
- Vite 环境变量与安全:vite.dev/guide/env-a…
- Stripe API keys(Safe to expose 标注):docs.stripe.com/keys
- 高德开放平台 Key 与安全密钥配置:lbs.amap.com/api/javascr…
- GitHub secret scanning 支持的模式:docs.github.com/en/code-sec…
- gitleaks:github.com/gitleaks/gi…
- trufflehog:github.com/trufflesecu…
- detect-secrets:github.com/Yelp/detect…
- secretlint:github.com/secretlint/…
- sm-crypto(SM2 / SM4 用法与默认模式):github.com/JuneAndGree…
- npm registry 版本信息:registry.npmjs.org/