机密信息管理与环境变量

在 React 应用中，环境变量分为两类：服务器端变量（绝不会发送到浏览器）和客户端变量（会嵌入 JavaScript 构建包）。了解变量属于哪一类，是进行机密信息管理的第一步，因为客户端变量一旦构建包部署，就实际上是公开的。

在 Vite 项目中，只有带有 VITE_ 前缀的变量才会包含在客户端构建包中。VITE_PUBLIC_API_URL=https://api.example.com 可以通过 import.meta.env.VITE_PUBLIC_API_URL 在浏览器代码中访问。所有其他变量都会在构建时从构建包中移除，并且仅保留在服务器端。

在 Next.js 中，NEXT_PUBLIC_ 前缀会将变量暴露给浏览器 JavaScript。NEXT_PUBLIC_ANALYTICS_ID=UA-123 会嵌入客户端构建包。没有此前缀的变量（例如 DATABASE_URL）只能在服务器端代码中访问（服务器组件、API 路由和服务器操作），绝不会发送到浏览器。

即使变量没有前缀，如果被意外序列化，仍然可能被访问。例如，如果服务器组件将完整配置对象作为属性传递给客户端组件，而该配置包含 DATABASE_URL，那么该机密信息就会出现在发送到浏览器的 HTML 中。谨慎地逐层传递属性并审计序列化过程，可以防止这种情况。

以下内容绝不能出现在客户端构建包中：数据库连接字符串和密码、第三方 API 机密密钥（Stripe 机密密钥、OpenAI API 密钥）、私有 RSA/EC 密钥、JWT 签名密钥以及内部服务身份验证令牌。如果 API 调用需要其中任何内容，请通过服务器端点代理该调用。

前端专用后端（BFF）模式在 React 应用和敏感外部服务之间放置一个精简的服务器层。客户端调用 /api/stripe/charge，BFF 服务器附加 Stripe 机密密钥并调用 Stripe API，然后 BFF 仅返回必要的响应数据。机密信息始终保留在服务器上。

dotenv-vault 会加密您的 .env 文件，使您能够在不同环境之间安全共享和部署，而无需将明文机密信息提交到版本控制系统。生产环境的替代方案包括 HashiCorp Vault（企业版）、AWS Parameter Store（SSM）和 GCP Secret Manager——它们都通过基于 API 的方式在运行时而非构建时获取机密信息。

CI/CD 平台（GitHub Actions、GitLab CI）提供加密的机密信息存储，可在构建期间作为环境变量访问。请将机密信息存储在 GitHub Secrets 中，并在工作流中以 ${{ secrets.STRIPE_SECRET_KEY }} 的形式引用。机密信息会在日志中被遮蔽，绝不会包含在构建产物中。

Next.js 和 Vite 支持多个 .env 文件：.env（所有环境）、.env.local（本地覆盖配置，被版本控制忽略）、.env.development、.env.production。本地文件会覆盖共享文件中的值，从而支持开发者特定的配置，而不会影响其他环境。

构建完成后，请审计 JavaScript 构建包，检查是否意外暴露了机密信息。请运行 grep -r "password|secret|api_key" dist/，或使用专用工具对构建后的文件进行 strings 分析。某些机密信息若被意外包含，可以通过其格式清楚识别（UUID、Base64 字符串，或类似 sk_live_ 的密钥前缀）。

每个环境和每项服务都只能访问其所需的机密信息。React 客户端根本不需要任何机密信息——它只应接收公开标识符。BFF 服务器只需要访问其所调用的 API 所必需的机密信息。开发环境应使用权限受限且设有支出上限的非生产环境 API 密钥。

带有 NEXT_PUBLIC_ 前缀的 Next.js 环境变量会发生什么？

Vite 使用 VITE_，Next.js 使用 NEXT_PUBLIC_ 将变量暴露给浏览器构建包。所有其他变量仅供服务器端使用。绝不要将数据库密码、API 机密密钥或 JWT 签名密钥包含在客户端代码中。请使用 BFF 模式代理敏感的 API 调用。请使用 dotenv-vault、AWS Parameter Store 或 GitHub Secrets 管理生产环境的机密信息。请审计构建包，检查是否意外暴露了机密信息。