求助：在Vercel中使用JavaScript/TypeScript无法访问环境变量

核心排查与修复步骤 #

1. 确认环境变量的配置范围与类型 #

Vercel的环境变量分环境（Development/Preview/Production）和运行端（服务器/客户端）：

• 检查你配置的TURSO_DATABASE_URL是否覆盖了当前构建的目标环境（比如构建Production时，变量是否在Production环境下配置）。
• 若在客户端组件/页面访问，变量名必须以NEXT_PUBLIC_开头，Vercel才会将其暴露给客户端代码；服务器端代码（API路由、Server Components、getServerSideProps等）使用则无需前缀，但要确保未误设为客户端专属变量。

2. 修正@t3-oss/env-nextjs的配置 #

使用该库时，必须严格遵循规则定义变量：

• 在env.mjs/env.ts中正确声明变量的归属（服务器/客户端）与校验规则，示例：

  import { createEnv } from "@t3-oss/env-nextjs";
  import { z } from "zod";
  
  export const env = createEnv({
    server: {
      TURSO_DATABASE_URL: z.string().url(),
    },
    client: {
      // 客户端变量需加NEXT_PUBLIC_前缀，在此声明
    },
    runtimeEnv: {
      TURSO_DATABASE_URL: process.env.TURSO_DATABASE_URL,
      // 对应客户端变量映射
    },
  });
  

• 代码中必须通过env.TURSO_DATABASE_URL访问，而非直接调用process.env；同时查看构建日志，确认zod校验未报错（校验失败会导致变量返回undefined）。

3. 清空Vercel构建缓存 #

旧缓存可能导致环境变量未更新：

• 在Vercel控制台的构建页面，选择「重新部署」并取消勾选「使用现有构建缓存」，强制触发全新构建。
• 本地开发时，重启Next.js开发服务器，确保.env文件变量被重新加载。

4. 验证变量注入情况 #

• 服务器端验证：在API路由或Server Components中添加日志，查看Vercel构建/函数日志确认变量是否存在：

  console.log("TURSO_DATABASE_URL:", process.env.TURSO_DATABASE_URL);
  

• 客户端验证：若为带NEXT_PUBLIC_前缀的变量，在客户端代码中打印window.NEXT_PUBLIC_XXX，确认是否被正确注入。

5. 检查Next.js版本与构建模式 #

确保使用稳定版Next.js；若采用静态生成（SSG），需确认getStaticProps中访问的服务器端变量在构建时已被Vercel正确注入。

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