本文介绍如何在 Next.js 应用中安全、高效地实现一次性的多域名地理重定向（如根据用户国家跳转至对应区域站点），避免 ERR_HTTP_HEADERS_SENT 错误，并确保重定向仅执行一次。
本文介绍如何在 next.js 应用中安全、高效地实现一次性的多域名地理重定向（如根据用户国家跳转至对应区域站点），避免 `err_http_headers_sent` 错误，并确保重定向仅执行一次。
在 Next.js 中，直接在 getInitialProps 或客户端 useEffect 中调用自定义重定向逻辑时，极易因重复响应写入（如多次调用 res.writeHead() / res.end()）触发 Error [ERR_HTTP_HEADERS_SENT]: Cannot set headers after they are sent to the client。根本原因在于：服务端渲染（SSR）与客户端渲染（CSR）环境混用、请求/响应对象生命周期管理不当，以及全局状态未做服务端-客户端隔离。
上述错误代码存在多个关键问题：
-
ctx.req._middlewareExecuted是非标准属性，且在 Vercel 边缘函数或 ISR 场景下不可靠； -
getInitialProps在服务端执行，但redirectMiddleware依赖req/res—— 而该函数又被错误地在客户端useEffect中无参调用（原答案示例中redirectMiddleware()缺失参数，将导致运行时崩溃）； - 使用全局变量
let redirectExecuted = false在服务端会跨请求共享状态（Node.js 单实例复用），造成严重竞态问题，绝对不可用于生产环境。
✅ 正确解法：将重定向逻辑移至 Next.js 13+ 的 middleware.ts（边缘运行时），利用 cookies() 实现“每用户仅一次”控制，并严格区分 SSR/CSR 执行路径。
✅ 推荐方案：使用 Next.js Middleware（推荐）
在项目根目录创建 middleware.ts（或 middleware.js）：
// middleware.ts
import { NextRequest, NextResponse } from 'next/server';
import { cookies } from 'next/headers';
export async function middleware(request: NextRequest) {
const cookieName = 'geo_redirect_done';
const cookie = cookies().get(cookieName);
// 若已标记重定向完成，跳过
if (cookie?.value === '1') {
return;
}
try {
// 从请求头获取 IP（Vercel 自动注入 X-Forwarded-For；本地开发可 fallback 到 localhost）
const ip = request.headers.get('x-forwarded-for') || '8.8.8.8';
// 调用 IP 地理信息 API（注意：生产环境应使用带缓存/配额管理的服务，或考虑 CDN 提供的 geo-header）
const res = await fetch(`https://ipinfo.io/${ip}/json?token=${process.env.IPINFO_TOKEN}`);
const data = await res.json();
const country = data.country || 'XX';
let redirectUrl = 'https://default-domain.com';
switch (country) {
case 'QA': redirectUrl = 'https://qatar.example.com'; break;
case 'US': redirectUrl = 'https://usa.example.com'; break;
case 'CA': redirectUrl = 'https://canada.example.com'; break;
default: redirectUrl = 'https://global.example.com';
}
// 设置 Cookie（HttpOnly + Secure + SameSite=Lax，有效期建议 1 年）
const response = NextResponse.redirect(redirectUrl, { status: 307 });
response.cookies.set({
name: cookieName,
value: '1',
httpOnly: true,
secure: process.env.NODE_ENV === 'production',
sameSite: 'lax',
maxAge: 60 * 60 * 24 * 365, // 1 year
path: '/',
});
return response;
} catch (err) {
console.warn('Geo-redirect failed, proceeding to original route:', err);
// 失败时不重定向，继续原请求
return;
}
}
// 指定此中间件作用于所有路由（可根据需要细化匹配）
export const config = {
matcher: '/:path*',
};
? 关键优势：
- 边缘执行：在 Vercel 边缘网络运行，毫秒级响应，不经过应用服务器；
- 天然幂等：通过
cookies().get()检查 +response.cookies.set()写入，确保每个用户仅触发一次；- 无 headers-sent 风险：
NextResponse.redirect()统一控制响应，无需手动操作res.writeHead()；- 服务端安全：Cookie 标记由服务端写入并校验，无法被客户端伪造绕过（配合
httpOnly）。
⚠️ 注意事项与最佳实践
-
API 限流与降级：
ipinfo.io免费版有请求限制（约 50k/月）。生产环境建议：- 使用
process.env.IPINFO_TOKEN配置令牌提升限额； - 添加
cache: 'force-cache'或自建 Redis 缓存层（IP → Country 映射）； - 或改用 CDN 提供的地理头（如 Cloudflare 的
CF-IPCountry），零额外请求。
- 使用
-
本地开发兼容性：
x-forwarded-for在localhost下可能为空，可在middleware.ts开头添加 fallback：const ip = request.headers.get('x-forwarded-for') || request.ip || '8.8.8.8'; // 测试用默认 IP -
SEO 友好性：使用
307 Temporary Redirect（而非301）可保留原始请求方法（如 POST），且不被搜索引擎缓存，便于后续策略调整。 -
避免客户端重定向：切勿在
useEffect中执行window.location.href = ...—— 这会导致首屏闪烁、SSR 失效、SEO 丢失，且无法设置 HttpOnly Cookie。
✅ 总结
要实现健壮的多域名地理重定向，请彻底放弃 getInitialProps + 自定义 req/res 操作的老模式。Next.js Middleware 是官方推荐、边缘优化、开箱即用的现代解决方案。 它天然解决 headers 发送冲突、状态持久化、执行时机等问题。配合 Cookie 标记与合理的降级策略，即可在生产环境稳定支撑百万级用户按地域分流。
如需进一步支持子路径重定向（如 /blog → qatar.example.com/blog），可在 NextResponse.redirect() 中构造完整 URL，或使用 request.nextUrl 进行路径拼接。
