VSCode中Next.js自定义环境变量API_URL无法被IntelliSense识别

核心排查方向 #

1. 环境变量命名规则（客户端访问必备） #

Next.js对客户端可访问的环境变量有强制要求：必须以NEXT_PUBLIC_为前缀。如果你的API_URL是在客户端组件中调用，直接写API_URL会导致浏览器无法读取——这是你说"无法访问API_URL"的核心原因。

• 客户端组件：改用NEXT_PUBLIC_API_URL=https://example.com
• 服务端组件：可直接使用不带前缀的API_URL，但需要类型声明补全提示

2. 添加类型声明补全IntelliSense #

在项目根目录新建types/env.d.ts文件（无types文件夹则直接创建），手动扩展ProcessEnv接口：

namespace NodeJS {
  interface ProcessEnv {
    // 服务端专用变量
    API_URL: string;
    // 客户端专用变量（带前缀）
    NEXT_PUBLIC_API_URL: string;
    NODE_ENV: 'development' | 'production' | 'test';
  }
}

然后在tsconfig.json中确保类型目录被识别：

{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./types"]
  }
}

3. 重启VSCode TypeScript服务 #

VSCode的TS服务可能缓存旧类型，按Ctrl+Shift+P（Windows/Linux）或Cmd+Shift+P（Mac），输入TypeScript: Restart TS Server，重启后IntelliSense即可识别自定义变量。

4. 匹配Server/Client组件的变量访问逻辑 #

• 服务端组件：直接用process.env.API_URL，无需前缀，但要确保变量在.env.local等文件中无拼写错误
• 客户端组件：必须用process.env.NEXT_PUBLIC_API_URL——客户端运行在浏览器，无法读取服务端私有环境变量，前缀是Next.js用来标记"需暴露给客户端"的标识，和新的组件机制直接相关

5. 确认环境文件加载优先级 #

Next.js环境文件加载顺序为：.env.local > .env.development/.env.production > .env，确保当前运行环境（如npm run dev对应development）加载的文件中变量未被重复定义覆盖。

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