持续集成中的环境变量
将机密存储在 GitHub Secrets 中，将其作为环境变量注入构建过程，并在 Vite 中通过 import.meta.env 或在 Next.js 中通过 process.env 访问。
持续集成中的环境变量 是 CoddyKit 上的免费 Frontend Academy 课时。 这是第 3 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 Frontend Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Frontend Academy 课程共包含 4 节课。
为什么需要不同的环境？
应用在不同环境中需要不同的值：开发环境 API URL、预发布环境 API URL、生产环境 API URL。此外，还有绝不能进入仓库的密钥（API 密钥、令牌）。环境变量是注入这些值的标准方式。
公开变量与仅限服务器使用的变量
构建到前端包中的前端变量是公开的，任何拥有 DevTools 的人都能看到它们。绝不要在那里放置密钥。服务器端变量（由无服务器函数、SSR 和 API 路由使用）才可以是真正的密钥。
Vite 环境变量
Vite 会通过 import.meta.env 将带有 VITE_ 前缀的变量暴露给客户端代码。
# .env
VITE_API_URL=https://api.example.com
VITE_FEATURE_FLAGS={"newOnboarding":true}
# In code:
const apiUrl = import.meta.env.VITE_API_URL;
# DEV_ONLY or NEVER PREFIXED vars are NOT exposed:
SECRET_KEY=xxx # not accessible to client codeNext.js 环境变量
Next 会为公开变量添加 NEXT_PUBLIC_ 前缀。仅限服务器使用的变量没有前缀（用于路由处理程序和 getServerSideProps）。
# .env.local
NEXT_PUBLIC_API_URL=https://api.example.com # client-accessible
DATABASE_URL=postgres://... # server-only
# Client:
const url = process.env.NEXT_PUBLIC_API_URL;
# Server (API route):
const db = process.env.DATABASE_URL;本地 .env 文件
使用 .env.local 保存个人覆盖值，使用 .env.development / .env.production 保存特定环境的默认值。将 .env.local 添加到 .gitignore 中，绝不要提交密钥。
# .gitignore
.env.local
.env.*.local
# Commit only .env.example with placeholder values:
VITE_API_URL=https://api.example.com
DATABASE_URL=在 GitHub Actions 中存储密钥
在仓库的 Settings → Secrets and variables → Actions 中添加密钥。通过 secrets.NAME 访问。
# .github/workflows/deploy.yml
- name: Deploy
env:
VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
run: |
npx vercel --token $VERCEL_TOKEN --prod
npx sentry-cli releases new $RELEASE特定环境的密钥
GitHub Environments（Settings → Environments）允许您将密钥限定在特定环境（预发布、生产）中，并可选择设置审批门槛。
# Job that requires environment:
deploy-prod:
environment: production # requires reviewer approval if configured
steps:
- run: deploy
env:
DB_URL: ${{ secrets.DB_URL }} # only prod's DB_URL is exposed托管平台的环境变量
Vercel、Netlify 和 Cloudflare 都会将环境变量暴露给您的构建过程和运行时。可在控制面板中设置，也可通过 CLI 设置。
# Vercel:
vercel env add VITE_API_URL production
vercel env add VITE_API_URL preview
# Netlify:
netlify env:set VITE_API_URL https://api.example.com
# Cloudflare Pages:
wrangler pages secret put API_URL不要将密钥硬编码到前端包中
如果某个值位于客户端 JS 中，它就是公开的。第三方 SDK 的 API 密钥（Stripe 可发布密钥、Algolia 搜索密钥）本来就设计为公开使用。其他任何密钥（服务器 API 密钥）都必须留在后端。
在构建时验证环境变量
使用 zod 或 envalid，在缺少必需环境变量时让构建失败。
// env.ts
import { z } from 'zod';
const envSchema = z.object({
VITE_API_URL: z.string().url(),
VITE_SENTRY_DSN: z.string().url().optional()
});
export const env = envSchema.parse(import.meta.env);
// Throws helpful error if VITE_API_URL is missing构建时变量与运行时变量
构建时环境变量会被写入包中，更改它们需要重新构建。运行时环境变量（Next API 路由、Netlify Functions、Cloudflare Workers）会针对每个请求进行求值。请根据该值是否需要在不重新部署的情况下发生变化来选择。
密钥轮换
定期轮换密钥（每 90 天一次），并在团队发生任何变动后进行轮换。使用 1Password Secrets Automation、AWS Secrets Manager 或类似工具，让 CI 中的密钥保持最新，而无需手动更新。
常见陷阱
1）提交包含真实密钥的 .env 文件——使用 git-secrets 加以阻止。2）将服务器变量暴露给客户端（前缀错误）。3）忘记在预览部署中设置环境变量。4）在同一环境中混用测试密钥和生产密钥。
快速检查
为什么暴露给客户端的 Vite 环境变量必须带有 VITE_ 前缀？
回顾：CI 中的环境变量
公开变量：带有前缀（VITE_、NEXT_PUBLIC_），会被写入包中，用户可以看到。仅限服务器使用的变量：没有前缀，用于 API 路由和 SSR。将 .env.local 添加到 .gitignore；提交 .env.example。使用 GitHub Secrets 管理 CI 密钥；使用 GitHub Environments 限定生产环境。托管平台（Vercel、Netlify、Cloudflare）都支持按环境设置变量。在构建时使用 zod 进行验证。
常见问题解答
「持续集成中的环境变量」课时是免费的吗？
是的 — 「持续集成中的环境变量」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Frontend Academy 课程的其余内容，请升级到 CoddyKit PRO。 Frontend Academy 课程共包含 4 节课。
「持续集成中的环境变量」这节课中我会学到什么？
将机密存储在 GitHub Secrets 中，将其作为环境变量注入构建过程，并在 Vite 中通过 import.meta.env 或在 Next.js 中通过 process.env 访问。 你通过在浏览器中直接运行的动手代码来练习 Frontend Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。
学习 Frontend Academy 需要有经验吗？
无需任何先前经验。CoddyKit 上的 Frontend Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 3 节课，共 4 节。
「持续集成中的环境变量」课时需要多长时间？
大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。
我能在这节 Frontend Academy 课中编写并运行代码吗？
能。每节 Frontend Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。