升级Node.js 18后SvelteKit SSR访问localhost突然失效的问题

问题原因 #

• Node.js 18起，内置fetch基于undici库实现，解析localhost时默认优先使用IPv6地址（::1）。
• 你的Django服务仅绑定了IPv4的127.0.0.1地址，未监听IPv6的::1端口，导致SSR阶段服务器端请求尝试连接::1:8000被拒绝。
• 客户端浏览器和手动工具能正常访问localhost:8000，是因为它们的DNS解析策略优先选择IPv4，或系统hosts配置让localhost同时映射到IPv4/IPv6，但Django未监听IPv6端口。

解决方法 #

1. 让Django监听IPv6地址 #

启动Django时指定绑定到::1（仅IPv6）或0.0.0.0（同时监听IPv4和IPv6）：

# 仅监听IPv6的localhost
python manage.py runserver ::1:8000

# 监听所有可用地址（IPv4+IPv6）
python manage.py runserver 0.0.0.0:8000

这样Django会响应::1:8000的请求，Node.js 18的fetch就能正常连接。

2. 强制SvelteKit SSR使用IPv4地址 #

将API请求地址从localhost:8000改为127.0.0.1:8000，强制使用IPv4连接，这是已验证有效的方案。可以通过统一配置API基础URL实现，比如在环境变量或配置文件中设置：

// 示例：src/lib/api.js
export const API_BASE_URL = process.env.NODE_ENV === 'production' 
  ? 'https://your-production-api.com' 
  : 'http://127.0.0.1:8000';

3. 调整Node.js的DNS解析优先级 #

启动Node.js时添加参数，强制优先解析IPv4：

node --dns-result-order=ipv4first node_modules/@sveltejs/kit/src/vite/dev/index.js

如果用pnpm管理项目，修改package.json的启动脚本：

"scripts": {
  "dev": "node --dns-result-order=ipv4first node_modules/@sveltejs/kit/src/vite/dev/index.js",
  "build": "node --dns-result-order=ipv4first node_modules/@sveltejs/kit/src/vite/build/index.js"
}

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