前置条件

• 已安装 Cursor（官网下载）
• 本地有正在运行的项目（Vite / Next.js / Node 服务等）

报错表现

Cursor 右上角提示 Unable to connect to dev server，终端显示：

1Error: connect ECONNREFUSED 127.0.0.1:5173

解决方法

先确认报错中的主机和端口，例如 127.0.0.1:5173。不要一开始就重装依赖或删除缓存；连接被拒绝通常表示该地址没有服务监听，应该按“进程 → 端口 → 地址 → 网络边界”的顺序排查。

第一步：确认开发服务器真的启动了

在项目目录运行启动命令，并保留终端输出：

1npm run dev

看到启动成功后，用浏览器或命令行直接访问报错中的地址：

1curl -I http://127.0.0.1:5173

如果这里也连接失败，问题在开发服务器本身，不在 Cursor。先查看启动终端最早出现的错误，而不是最后一行堆栈。

方法一：检查端口是否被占用

1# Windows2netstat -ano | findstr :51733 4# macOS / Linux5lsof -i :5173

如果端口已有进程监听，先确认它是否就是当前项目。不要直接结束陌生进程；可以让项目换一个明确端口，再更新 Cursor 中使用的地址。

方法二：清理缓存后重新启动

Cursor 有时会缓存旧的连接信息。执行以下步骤：

1. 在 Cursor 右上角点击 Stop 停止当前会话
2. 关闭 Cursor 窗口
3. 将 .next 或 node_modules/.vite 缓存目录临时改名，保留回退可能
4. 重新 npm run dev
5. 重新打开 Cursor

方法三：检查 hosts 文件

部分情况下 localhost 解析异常也会导致连接被拒绝：

1# 检查 /etc/hosts (macOS/Linux) 或 C:\Windows\System32\drivers\etc\hosts2127.0.0.1       localhost

方法四：检查监听地址和容器边界

如果项目运行在 Docker、WSL、远程 SSH 或开发容器中，localhost 可能只代表容器内部。让开发服务器监听所有接口，并使用宿主机可以访问的端口：

1# Vite 示例2npm run dev -- --host 0.0.0.03 4# Next.js 示例5npm run dev -- --hostname 0.0.0.0

同时确认 Docker 已映射端口，例如 5173:5173。只在可信网络中开放开发端口，公共服务器应由防火墙或反向代理限制访问。

推荐诊断顺序

1. 查看启动终端是否已经报错退出
2. 用浏览器或 curl 直接访问目标地址
3. 检查实际监听端口是否与报错一致
4. 检查服务监听的是 127.0.0.1 还是 0.0.0.0
5. 检查 Docker、WSL、SSH 端口转发
6. 最后再检查代理、VPN、防火墙和 hosts

修复完成后，连续刷新两次页面，并重启一次开发服务器。如果端口、热更新和 API 请求都正常，才算问题真正解决。

常见报错

相关资源

本篇涉及的开发环境配置问题，如有需要可在商店了解相关 项目模板，包含开箱即用的开发环境配置。

更新记录

• 2026-05-06：首发