T3-Env在GitHub Actions中的环境变量配置实践

问题背景

T3-Env是一个用于Next.js项目的环境变量管理工具，它能够帮助开发者安全、高效地管理不同环境下的配置。在实际开发中，很多开发者会遇到本地开发环境(dev)和生产环境(prod)下T3-Env工作正常，但在GitHub Actions中却无法正确读取环境变量的问题。

问题现象

当项目在GitHub Actions中运行时，T3-Env无法正确识别配置的环境变量，导致构建失败。具体表现为环境变量校验失败，提示缺少必要的环境变量值。

原因分析

经过深入分析，这个问题通常由以下几个原因导致：

1. 环境变量作用域不同：GitHub Actions中的环境变量与本地开发环境的作用域机制不同
2. 变量传递方式差异：在GitHub Actions中，环境变量需要通过特定方式注入到工作流中
3. 安全策略限制：GitHub对公开仓库中的环境变量有特殊的安全处理机制

解决方案

使用GitHub仓库机密(Secrets)

最可靠且安全的解决方案是使用GitHub仓库的Secrets功能来存储敏感的环境变量：

1. 在GitHub仓库设置中进入"Secrets and variables"部分
2. 添加与项目所需环境变量对应的仓库机密
3. 在工作流文件中通过env部分引用这些机密

工作流文件配置示例

在GitHub Actions的工作流文件中，应该这样配置环境变量：

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      NEXT_PUBLIC_BASE_URL: ${{ secrets.NEXT_PUBLIC_BASE_URL }}
      NEXT_PUBLIC_SITE_NAME: ${{ secrets.NEXT_PUBLIC_SITE_NAME }}
    steps:
      - uses: actions/checkout@v3
      - run: npm install
      - run: npm run build

T3-Env配置保持原样

T3-Env的配置文件(如env/client.ts)无需修改，保持原有结构即可：

import { createEnv } from "@t3-oss/env-nextjs";
import { z } from "zod";

export const env = createEnv({
  isServer: typeof window === "undefined",
  client: {
    NEXT_PUBLIC_BASE_URL: z.string().url(),
    NEXT_PUBLIC_SITE_NAME: z.string(),
  },
  runtimeEnv: {
    NEXT_PUBLIC_BASE_URL: process.env.NEXT_PUBLIC_BASE_URL,
    NEXT_PUBLIC_SITE_NAME: process.env.NEXT_PUBLIC_SITE_NAME,
  },
});

安全实践建议

1. 区分公共和私有变量：NEXT_PUBLIC前缀的变量会被嵌入客户端代码中，非公共变量应避免使用此前缀
2. 最小权限原则：只给CI/CD流程必要的环境变量权限
3. 定期轮换机密：定期更新存储在GitHub Secrets中的敏感信息
4. 审计日志：定期检查谁访问了仓库机密

总结

通过使用GitHub仓库的Secrets功能来管理CI/CD流程中的环境变量，不仅解决了T3-Env在GitHub Actions中无法读取环境变量的问题，还提升了项目的整体安全性。这种方案既保持了开发环境的配置一致性，又符合现代应用的安全最佳实践。