如何为Next.js中next.config.js内的环境变量实现t3-env类型安全

报错原因 #

你在env.ts里直接引用next.config.js中的变量时出错，核心原因有两个：

1. 这些变量没在client或server区块中定义对应的Zod校验规则，t3-env无法识别它们的类型。
2. TypeScript默认不知道process.env上存在这些自定义属性，会抛出类型提示错误。

解决步骤 #

1. 在env.ts中添加变量的Zod校验规则 #

next.config.js的env字段中配置的变量会直接暴露给客户端（和带NEXT_PUBLIC_前缀的变量行为一致），所以要把它们放在client区块里定义校验规则：

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

export const env = createEnv({
  server: {
    DATABASE_URL: z.string().url(),
  },
  
  client: {
    NEXT_PUBLIC_BASE_URL: z.string().url(),
    // 新增next.config.js中变量的校验规则
    siteName: z.string(),
    facebookUrl: z.string().url(),
    twitterUrl: z.string().url(),
    pinterestUrl: z.string().url(),
    linkedinUrl: z.string().url(),
    youtubeUrl: z.string().url(),
  },
  
  runtimeEnv: {
    // 原有.env文件的变量映射
    DATABASE_URL: process.env.DATABASE_URL,
    NEXT_PUBLIC_BASE_URL: process.env.NEXT_PUBLIC_BASE_URL,
    
    // 映射next.config.js中的变量
    siteName: process.env.siteName,
    facebookUrl: process.env.facebookUrl,
    twitterUrl: process.env.twitterUrl,
    pinterestUrl: process.env.pinterestUrl,
    linkedinUrl: process.env.linkedinUrl,
    youtubeUrl: process.env.youtubeUrl,
  },
});

2. 扩展TypeScript全局类型（可选但推荐） #

为了让TypeScript在整个项目中都能识别这些环境变量的类型，你可以在项目根目录创建types/env.d.ts文件（没有types目录就新建一个），添加以下内容：

declare global {
  namespace NodeJS {
    interface ProcessEnv {
      siteName: string;
      facebookUrl: string;
      twitterUrl: string;
      pinterestUrl: string;
      linkedinUrl: string;
      youtubeUrl: string;
    }
  }
}

export {};

3. 更优替代方案（推荐） #

其实更符合t3-env和Next.js最佳实践的方式是把这些客户端变量移到.env文件中，用NEXT_PUBLIC_前缀命名，这样不需要在next.config.js中额外配置，t3-env会自动处理类型安全，还能保持配置的集中性。

示例.env文件：

NEXT_PUBLIC_SITE_NAME=The Custom Crow
NEXT_PUBLIC_FACEBOOK_URL=https://www.facebook.com/drippy.in/
NEXT_PUBLIC_TWITTER_URL=https://twitter.com/drippy_in
NEXT_PUBLIC_PINTEREST_URL=https://www.pinterest.com/drippy_in/
NEXT_PUBLIC_LINKEDIN_URL=https://www.linkedin.com/company/drippy-in/
NEXT_PUBLIC_YOUTUBE_URL=https://www.youtube.com/channel/UC2sDh9f6i7hjZx2i0rY3N8Q

然后在env.ts的client区块中定义对应的校验规则即可，这样配置更简洁，也更符合Next.js的环境变量使用规范。

内容的提问来源于stack exchange，提问作者Rishabh