解决网站部署后页面一直 Loading 的问题

问题描述

昨天把博客部署到 Cloudflare Pages 后，访问页面一直卡在 Loading 状态，控制台没有任何报错。本地开发环境完全正常，只有线上有问题。

排查过程

第一步：检查构建产物

首先怀疑是构建产物有问题。检查了 out 目录，HTML 文件都在，内容也正常。用本地的静态文件服务器测试：

cd out
npx serve

本地一切正常。说明问题不在构建产物本身。

第二步：检查 Cloudflare 配置

检查了项目的构建设置，build command 和 output directory 都对。又检查了 Functions 和重定向规则，也没有异常。

第三步：检查浏览器网络请求

打开 DevTools 的 Network 面板，发现页面加载后发了一个 API 请求，地址是 undefined/api/posts。这个请求当然会失败，但页面没有处理这个错误，一直卡在 Loading。

根本原因

是环境变量的问题。Next.js 的 static export 模式下，process.env 在运行时不可用。代码里用了 process.env.NEXT_PUBLIC_API_URL，但这个变量在 Cloudflare Pages 的构建环境中没有设置。

构建时，Next.js 会把 process.env.NEXT_PUBLIC_API_URL 替换成实际的值。如果没设置，就会变成 undefined，导致 API 请求发到了 undefined/api/posts。

解决方案

方案一：在 next.config.ts 里硬编码

// next.config.ts
const nextConfig = {
  env: {
    NEXT_PUBLIC_API_URL: "https://api.example.com",
  },
};

方案二：改用构建时确定的值

把 API 地址写在一个配置文件里，不依赖环境变量：

// lib/config.ts
export const API_URL = "https://api.example.com";

我选择了方案二，因为更明确，不会有运行时不确定的问题。

经验教训

static export 模式下，所有数据必须在构建时确定。不要依赖运行时的环境变量，否则在不同的部署平台上可能会出现诡异的问题。

改完重新部署，页面正常加载了。