Next.js项目Vercel部署遇Endpoint URL格式错误求助

问题根源 #

部署过程中process.env.NEXT_PUBLIC_FAAQT_API_URL未正确加载，导致拼接后的API URL无效，触发页面预渲染失败。

解决方案 #

1. 确认Vercel环境变量配置 #

• 登录Vercel控制台，进入目标项目的Settings > Environment Variables
• 检查NEXT_PUBLIC_FAAQT_API_URL是否存在，值需严格匹配https://backend.faaqt.com/v1/
• 务必勾选Deployments选项，确保变量在构建阶段（预渲染执行阶段）可用

2. 验证环境变量加载状态 #

在API调用函数中添加临时日志（部署后可移除），确认变量是否正常加载：

export const login = async (data: LoginData) => {
  // 临时日志，用于验证变量加载情况
  console.log('Loaded API URL:', process.env.NEXT_PUBLIC_FAAQT_API_URL);
  
  const { email, password } = data;
  const response = await fetch(
    `${process.env.NEXT_PUBLIC_FAAQT_API_URL}auth/login`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email, password })
    }
  );
  return response.json();
};

部署后查看Vercel构建日志，搜索Loaded API URL，确认变量值正确输出。

3. 为API调用添加容错逻辑 #

避免因变量为空/无效导致错误，在代码中增加校验：

export const login = async (data: LoginData) => {
  const { email, password } = data;
  const baseUrl = process.env.NEXT_PUBLIC_FAAQT_API_URL;

  // 校验baseUrl的有效性
  if (!baseUrl || !/^https?:\/\//.test(baseUrl)) {
    throw new Error('API base URL配置无效，请检查环境变量');
  }

  const response = await fetch(
    `${baseUrl}auth/login`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email, password })
    }
  );
  return response.json();
};

4. 检查预渲染页面的API调用时机 #

• 如果页面使用getStaticProps/getServerSideProps预渲染，确保API调用仅在这些数据获取函数内部执行，不要在组件渲染阶段直接调用异步API
• 若仅服务器端需要使用的变量，可去掉NEXT_PUBLIC_前缀；但如果是客户端和构建阶段都需要的变量，保留前缀是正确配置

5. 重新触发部署 #

确认环境变量配置无误后，在Vercel控制台的Deployments页面选择最新部署，点击Redeploy，确保新的环境变量生效。

内容的提问来源于stack exchange，提问作者Rubén Colomina Citoler