坑所属项目 ↗2026-10-03

Astro Preview 端口被占自动迁移 + IPv6 监听导致 127.0.0.1 连不上

astro preview 指定端口被占时自动迁移到新端口（4321→4322），且默认只监听 ::1（IPv6）；用 curl 127.0.0.1（IPv4）会"无法连接"，实际服务是好的。解法：看 preview 日志找真实端口，用 localhost（IPv6）访问。

  • Astro
  • Preview
  • 端口
  • IPv6

现象

astro preview --port 4321 启动后 curl http://127.0.0.1:4321/... 报”无法连接到远程服务器”，误判服务未起来。

排查

看 preview.log 发现：

Port 4321 is in use, trying another one...
astro v7.3.1 ready in 16 ms
Local  http://localhost:4322/

再看 Get-NetTCPConnection -State Listen：

::1  4321  21640   ← 早先的 dev 进程（IPv6）
::1  4322  22952   ← 本次 preview（IPv6）

两个关键事实：

  1. 端口被占会自动迁移，最终端口以日志输出为准，不是启动参数
  2. 默认只监听 ::1（IPv6），IPv4 的 127.0.0.1 上根本没有监听，所以连不上

修复

  • 用 localhost 访问（解析到 ::1）：Invoke-WebRequest http://localhost:4322/... → HTTP 200
  • 或确认实际监听地址后再选 URL；不要只看启动参数里的端口

注意

  • 验证本地 Astro 服务时：①先查 preview.log 的真实端口 ②curl 用 localhost 而非 127.0.0.1
  • 排查”服务没起来”先用 Get-NetTCPConnection -State Listen 看实际监听（地址+端口+进程），再下结论
← 返回全部归档