跳到主要内容解决前端 Axios 请求 Net::ERR_CONNECTION_REFUSED 连接拒绝问题 | 极客日志JavaScriptNode.js大前端java
解决前端 Axios 请求 Net::ERR_CONNECTION_REFUSED 连接拒绝问题
前端 Axios 发起 HTTP 请求时出现 Net::ERR_CONNECTION_REFUSED 错误的排查方法。该错误属于 TCP 层异常,核心原因是客户端无法与服务端建立基础连接。排查需从服务端运行状态、前端请求配置、网络链路通畅性、端口防火墙限制四个维度进行。涵盖本地开发、局域网及线上生产场景,提供验证步骤、代理配置示例及 curl/Postman 终极测试方案,帮助快速定位并解决连接拒绝问题。
并发大师29 浏览 Net::ERR_CONNECTION_REFUSED 是前端使用 Axios 发起 HTTP 请求时,最常见的网络层错误之一。该错误的出现与 Axios 语法、接口请求参数无关,也并非前端代码逻辑问题,核心是前端客户端无法与目标服务端建立基础的 TCP 连接,服务端对客户端发起的连接请求做出了拒绝响应。这类问题的排查需跳出前端代码本身,从「服务端运行状态」「前端请求配置」「网络链路通畅性」「端口/防火墙限制」四个核心维度逐步验证,本地开发环境还需额外检查代理转发配置,以下是从易到难的完整排查流程和针对性解决方案,覆盖本地、局域网、线上生产所有开发场景。
一、核心认知:错误本质与核心诱因
在解决问题前,先明确该错误的底层逻辑,能避免盲目排查——该错误属于TCP/IP 网络层异常,而非 HTTP 应用层异常,出现时客户端的请求甚至未能到达服务端的接口处理逻辑,仅在「建立 TCP 连接」阶段就被阻断。
1.1 错误的核心本质
TCP 协议建立连接时需经过「三次握手」,Net::ERR_CONNECTION_REFUSED 表示:前端客户端向服务端的指定 IP+ 端口发送了 TCP 连接请求,但服务端未对该请求做出任何响应,直接拒绝了连接,导致三次握手无法完成,请求链路直接中断。
1.2 触发错误的四大核心诱因
所有场景下的连接拒绝,最终都能归为以下四类原因,按出现频率从高到低排序:
- 服务端未启动/启动失败:目标服务端的后端项目未运行,或启动时因代码错误、端口占用等原因崩溃,无进程监听指定端口;
- 前端请求配置错误:Axios 的请求地址(URL)、端口号、协议(http/https)与服务端实际配置不匹配,请求了错误的目标地址;
- 网络链路不通:前端与服务端不在同一网络(如局域网开发时跨网段)、防火墙/安全软件拦截了连接请求、云服务器安全组未放行端口;
- 开发环境代理配置错误:Vue/React 等项目通过 devServer 配置了接口代理,代理的目标地址(target)写错,导致请求被转发到无效地址,触发连接拒绝。
1.3 关键区分:避免与其他错误混淆
开发中易将该错误与跨域、接口 404/500 混淆,需通过错误提示精准区分,避免排查方向偏离:
- Net::ERR_CONNECTION_REFUSED:TCP 连接建立失败,请求未到服务端;
- CORS 跨域错误:TCP 连接成功,请求已到服务端,仅 HTTP 层面因跨域策略被拦截;
- 404 Not Found:TCP 连接+HTTP 请求均成功,服务端未找到对应接口;
- 500 Internal Server Error:TCP 连接+HTTP 请求均成功,服务端处理接口时内部报错。
二、从易到难:分步排查与针对性解决方案
排查遵循**「先确认服务端→再检查前端本地配置→最后验证网络链路」**的原则,从最容易验证、出现频率最高的原因开始,逐步缩小排查范围,所有步骤均提供具体的验证方法和解决操作,新手也能直接跟进。
步骤 1:验证目标服务端是否正常运行,有无进程监听指定端口
这是触发 Net::ERR_CONNECTION_REFUSED最核心、最常见的原因,优先验证该点,能解决 80% 以上的问题。核心验证逻辑:确认服务端有进程正常监听 Axios 请求的「IP+ 端口」。
具体验证方法
- 检查服务端启动日志:打开后端项目的启动终端/日志文件,查看是否有「启动成功」「监听端口 xxx」的提示,若有代码错误、端口占用等提示,说明服务端启动失败;
- 手动访问服务端地址:在浏览器地址栏直接输入服务端的基础地址(如
http://localhost:3000、http://192.168.1.100:8080),若浏览器显示「无法访问此网站」且控制台报相同的连接拒绝错误,说明服务端未启动/无进程监听端口;
- 检查端口是否被占用/有无监听进程:通过命令行查看指定端口是否有进程在监听,不同系统命令不同:
Mac/Linux 系统:打开终端,执行命令(替换为实际端口号):
lsof -i:8080
netstat -tulpn | grep 8080
Windows 系统:打开 CMD/PowerShell,执行命令(替换为实际端口号):
netstat -ano | findstr "8080"
若执行后无任何输出,说明该端口无进程监听;若有输出,可通过 PID 查看对应进程是否为目标后端服务。
针对性解决方案
- 重新启动后端服务:若服务端未启动,直接运行后端项目的启动命令(如 Java 的
java -jar xxx.jar、Node.js 的 node app.js、SpringBoot 的 IDE 启动);
- 解决服务端启动失败问题:若启动日志有报错,按错误提示修复(如代码语法错误、依赖缺失);若提示端口被占用,要么杀死占用端口的进程,要么修改后端服务的监听端口;
- 杀死占用端口进程:Windows 通过「任务管理器」根据 PID 结束进程,Mac/Linux 执行
kill -9 进程 PID;
- 修改后端端口:如 SpringBoot 修改
application.yml 的 server.port,Node.js 修改 app.listen(新端口);
- 确认服务端监听的是正确端口:确保后端服务监听的端口,与前端 Axios 请求的端口完全一致。
步骤 2:检查前端 Axios 请求配置,确保地址/端口/协议完全正确
服务端启动正常后,若仍报连接拒绝,需检查前端请求配置——请求地址拼写错误、端口号写错、http/https 混用是前端开发中高频的低级错误。
具体验证方法
- 查看 Axios 的实际请求地址:打开浏览器 F12→Network面板,找到报红的请求,查看Request URL列,确认实际请求的地址是否为服务端的真实地址;
- 核对 Axios 的基础配置:检查项目中 Axios 的
baseURL 配置(全局配置)或单个请求的 url(局部配置),重点核对 3 点:
- 协议:服务端用
http 则前端不能写 https(如服务端是 http://localhost:3000,前端写 https://localhost:3000 会直接拒绝);
- 域名/IP:本地开发常用
localhost/127.0.0.1,局域网开发需用服务端的本机 IP(如 192.168.1.105),不能用 localhost;
- 端口号:与服务端监听的端口完全一致,无多写/少写数字(如服务端 3000,前端写 3001);
- 检查是否有硬编码的错误地址:部分开发会在单个请求中硬编码 url,覆盖了全局
baseURL,需排查是否有此类情况。
针对性解决方案
- http/https 严格与服务端保持一致:若服务端未配置 HTTPS 证书,前端绝对不能用
https 协议发起请求,直接改为 http。
单个请求仅写接口路径,不写完整地址:基于全局 baseURL,单个请求只需写接口后缀,避免协议/端口错误:
service.get('/api/user/list')
统一 Axios 的全局 baseURL 配置:推荐在项目中全局配置 Axios 的 baseURL,避免单个请求硬编码,减少错误率,示例:
import axios from 'axios'
const service = axios.create({
baseURL: 'http://192.168.1.105:3000',
timeout: 5000
})
export default service
步骤 3:验证前端与服务端的网络链路是否通畅,无防火墙/安全软件拦截
服务端启动正常、前端配置正确后,仍报连接拒绝,需排查网络链路——前端和服务端不在同一网络、防火墙拦截连接是局域网/线上开发的常见原因。
具体验证场景与方法
按「本地开发→局域网开发→线上开发」分场景验证,核心逻辑:确保前端能通过网络访问到服务端的 IP+ 端口。
- 本地开发场景(前端 + 服务端在同一台电脑)
- 验证:用
localhost/127.0.0.1 访问服务端地址,若 localhost 能访问、127.0.0.1 不能,大概率是本地 hosts 文件配置错误;
- 额外检查:关闭本地的杀毒软件、防火墙(如 Windows Defender、360 安全卫士),部分安全软件会拦截本地端口的连接请求。
- 局域网开发场景(前端 + 服务端在不同电脑,同一局域网)
- 验证 1:前端电脑通过「ping 服务端 IP」测试网络连通性,如
ping 192.168.1.105,若出现「请求超时」,说明两台电脑不在同一网段/局域网不通;
- 验证 2:前端电脑在浏览器直接访问服务端的「IP+ 端口」,如
http://192.168.1.105:3000,若报连接拒绝,说明服务端电脑的防火墙拦截了请求;
- 关键注意:局域网开发时,前端 Axios 的
baseURL 必须写服务端的本机 IP,不能写 localhost(localhost 仅指向当前电脑)。
- 线上生产场景(前端部署在服务器/CDN,服务端部署在云服务器)
- 验证 1:本地电脑通过浏览器访问线上服务端的「域名/公网 IP+ 端口」,如
https://api.xxx.com:8080,若报连接拒绝,说明云服务器的端口未开放;
- 验证 2:检查云服务器的安全组规则(阿里云/腾讯云/华为云均有),这是线上场景最容易忽略的点——云服务器的端口需在安全组中手动放行,否则即使服务端启动、服务器防火墙关闭,外部也无法访问;
- 验证 3:检查服务端服务器的系统防火墙(如 Linux 的 iptables/firewalld,Windows 的防火墙),确保放行目标端口。
针对性解决方案
- 本地开发:修复 hosts 文件(
C:\Windows\System32\drivers\etc\hosts),确保 127.0.0.1 localhost 未被注释;临时关闭杀毒软件/防火墙,测试是否能连接。
- 局域网开发:
- 将前端和服务端电脑连接到同一 WiFi/交换机,确保在同一网段(IP 前三位相同,如 192.168.1.x);
- 关闭服务端电脑的系统防火墙:Windows 在「设置→更新和安全→Windows 安全→防火墙和网络保护」中关闭;Linux 执行
systemctl stop firewalld(临时关闭);
- 线上生产场景:
- 云服务器安全组放行端口:在云服务器控制台的「安全组」中,添加入站规则,放行服务端的监听端口(如 8080、3000),允许所有 IP 访问(0.0.0.0/0);
- 服务器系统防火墙放行端口:Linux 通过 iptables/firewalld 添加端口放行规则,Windows 在防火墙高级设置中添加入站规则;
- 确认服务端绑定的是公网 IP:后端服务启动时,确保监听的是
0.0.0.0(所有 IP),而非 127.0.0.1(仅本地访问),如 Node.js 的 app.listen(3000, '0.0.0.0')。
步骤 4:检查开发环境的代理配置,确保代理转发地址正确
Vue/React/Vite 等前端项目,为了解决本地开发的跨域问题,会通过 devServer.proxy(webpack)/server.proxy(Vite)配置接口代理——代理的 target 地址写错是开发中极易忽略的点,此时前端请求的是本地代理地址,代理服务器转发到错误的服务端地址,最终触发连接拒绝。
具体验证方法
- 确认项目是否配置了代理:查看项目配置文件(Vite 为
vite.config.js,Vue2 为 vue.config.js,React 为 src/setupProxy.js),是否有 proxy 相关配置;
- 检查代理的 target 地址:核心核对代理的
target 是否为服务端的真实地址(协议+IP+ 端口),是否存在端口、协议写错的情况;
- 验证代理是否生效:打开浏览器 Network 面板,查看 Axios 的请求地址是否为本地项目地址(如
http://localhost:8080/api/user),而非服务端地址,若为本地地址,说明代理已生效,需重点检查 target。
针对性解决方案
核心原则:代理的 target 必须是服务端的真实可访问地址,且配置后需重启前端项目(代理配置修改后不重启不生效),以下给出主流框架的代理正确配置示例。
示例 1:Vue3/Vite 项目(vite.config.js)
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
export default defineConfig({
plugins: [vue()],
server: {
port: 8080,
proxy: {
'/api': {
target: 'http://192.168.1.105:3000',
changeOrigin: true,
rewrite: (path) => path.replace(/^\/api/, '')
}
}
}
})
示例 2:Vue2/@vue/cli 项目(vue.config.js)
module.exports = {
devServer: {
port: 8080,
proxy: {
'/api': {
target: 'http://localhost:3000',
changeOrigin: true,
pathRewrite: { '^/api': '' }
}
}
}
}
示例 3:React/create-react-app 项目(src/setupProxy.js)
需先安装 http-proxy-middleware:npm install http-proxy-middleware --save-dev
const { createProxyMiddleware } = require('http-proxy-middleware')
module.exports = function(app) {
app.use('/api', createProxyMiddleware({
target: 'http://192.168.1.105:3000',
changeOrigin: true,
pathRewrite: { '^/api': '' }
}))
}
关键代理配置注意点
changeOrigin: true 是必配项,开启后代理服务器会模拟服务端的域名,避免跨域;
- 代理配置修改后,必须重启前端项目,否则配置不生效;
- 前端 Axios 的
baseURL 需配置为前端项目的本地地址(如 http://localhost:8080),才能触发代理转发。
步骤 5:终极验证:通过 curl/postman 测试,排除前端项目环境问题
若以上步骤均验证无误,仍报连接拒绝,需排除前端项目本身的环境问题(如依赖冲突、配置污染),通过curl 命令或Postman直接发起请求,测试服务端地址是否可访问。
具体验证方法
- Postman 测试:打开 Postman,输入服务端的接口地址,发起请求,若能正常响应,说明服务端和网络均无问题,问题出在前端项目。
curl 命令测试:打开前端电脑的终端/CMD,执行 curl 命令(替换为服务端真实地址):
curl http://192.168.1.105:3000/api/user/list
curl -X POST -d "name=test" http://192.168.1.105:3000/api/user/add
若 curl 命令也报「Connection refused」,说明问题与前端项目无关,回到步骤 3 重新排查网络/防火墙;若 curl 命令能正常获取接口返回值,说明前端项目环境有问题。
针对性解决方案
若 curl/Postman 能正常访问,仅前端项目报连接拒绝,按以下步骤处理:
- 重启前端项目,清除项目缓存(如 Vite 的
node_modules/.vite,webpack 的 node_modules/.cache);
- 重新安装 Axios 依赖:
npm uninstall axios && npm install axios,排除依赖损坏问题;
- 检查项目中是否有其他网络相关配置(如 mock 服务、请求拦截器),是否拦截/修改了 Axios 的请求地址;
简化请求代码,用原生 fetch 测试,排除 Axios 本身的问题:
fetch('http://192.168.1.105:3000/api/user/list')
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.log(err))
三、不同开发场景的专属排查重点
不同的开发场景(本地/局域网/线上),触发连接拒绝的核心原因不同,针对性聚焦排查重点,能大幅提升排查效率,以下是各场景的核心排查点总结:
场景 1:本地开发(前端 + 服务端在同一台电脑)
- 服务端是否正常启动,有无进程监听指定端口;
- 前端 Axios 的地址是否为
localhost/127.0.0.1,端口与服务端一致;
- 本地杀毒软件/防火墙是否拦截了端口连接;
- 代理配置的 target 是否为
localhost/127.0.0.1+ 正确端口。
场景 2:局域网开发(前端 + 服务端在不同电脑)
- 前端和服务端是否连接到同一 WiFi/交换机,是否在同一网段;
- 前端 Axios/代理的地址是否为服务端的本机 IP(不能用 localhost);
- 服务端电脑的系统防火墙是否关闭,是否放行目标端口;
- 服务端是否监听
0.0.0.0(而非 127.0.0.1),允许局域网访问。
场景 3:线上生产场景(前端/服务端部署在服务器)
- 云服务器的安全组规则是否放行服务端的监听端口(入站规则);
- 服务器的系统防火墙(iptables/firewalld)是否放行目标端口;
- 服务端是否监听
0.0.0.0,允许公网访问;
- 前端 Axios 的地址是否为服务端的公网 IP/域名,协议(http/https)与服务端一致;
- 服务端部署后是否正常启动,有无进程监听指定端口(通过
lsof -i:端口 验证)。
四、高频避坑点:这些细节会导致排查反复
即使掌握了排查步骤,若忽略以下细节,仍会出现「排查后仍报错误」的情况,这些是开发中极易踩坑的点,需重点注意:
避坑 1:代理配置修改后未重启前端项目
代理配置(vite.config.js/vue.config.js)属于项目启动时的静态配置,修改后若不重启前端项目,配置不会生效,前端仍会按旧的 target 地址转发请求,导致连接拒绝。
解决方案:修改代理配置后,必须执行 npm run dev/serve 重启项目。
避坑 2:服务端绑定 127.0.0.1,拒绝局域网/公网访问
后端服务启动时,若监听的是 127.0.0.1,则仅允许服务端本机访问,局域网/公网的前端请求会被直接拒绝;正确的做法是监听 0.0.0.0,允许所有 IP 访问。
示例:Node.js 服务端正确监听配置
app.listen(3000, '0.0.0.0', () => console.log('服务启动'))
避坑 3:线上云服务器只关闭系统防火墙,未配置安全组
云服务器(阿里云/腾讯云)有安全组和系统防火墙两层防护,即使关闭了系统防火墙,若安全组未放行端口,外部请求仍会被拒绝;安全组是云服务器的第一道防护,必须优先配置。
解决方案:在云服务器控制台,找到对应实例的安全组,添加入站规则,放行服务端端口,来源选择「0.0.0.0/0」(允许所有 IP)。
避坑 4:http 和 https 混用,服务端无 HTTPS 证书仍用 https 请求
若服务端未配置 SSL 证书,未开启 HTTPS 服务,前端强行用 https 协议发起请求,会直接触发 TCP 连接拒绝;协议必须严格匹配,无证书则用 http,有证书则用 https。
避坑 5:局域网开发时,前端 Axios 写 localhost 而非服务端 IP
localhost 和 127.0.0.1 均指向当前电脑,局域网开发时,前端电脑的 localhost 指向前端本身,而非服务端电脑,请求 localhost 会导致连接到前端电脑的无效端口,触发拒绝。
解决方案:局域网开发时,前端所有请求地址必须写服务端的本机 IP(如 192.168.1.105)。
五、总结:Net::ERR_CONNECTION_REFUSED 通用排查流程
Axios 请求报 Net::ERR_CONNECTION_REFUSED 的排查,核心是跳出前端代码,聚焦「TCP 连接建立」的全链路,该错误与 Axios、前端逻辑无关,只需按「从易到难、分场景聚焦」的原则逐步验证,以下是可直接套用的通用排查流程,覆盖所有场景:
通用排查步骤(按执行顺序)
- 验证服务端:检查服务端是否正常启动,有无进程监听目标端口,启动日志是否无报错;
- 验证前端配置:检查 Axios 的 baseURL/请求 url,确保协议、IP/域名、端口与服务端完全一致;
- 验证网络链路:本地/局域网/线上按对应场景,检查网络是否连通、防火墙/安全组是否放行端口;
- 验证代理配置:开发环境检查 proxy 的 target 地址是否正确,修改后是否重启前端项目;
- 终极验证:用 curl/Postman 测试服务端地址,排除前端项目环境问题;
- 细节检查:确认服务端监听 0.0.0.0、无 http/https 混用、无端口占用。
核心解决思路(3 句话概括)
- 先定服务端:服务端未启动/无端口监听是核心原因,优先验证并确保服务端正常运行;
- 再核配置:前端请求地址、代理 target 的协议/IP/端口,必须与服务端完全一致,无任何拼写错误;
- 最后查网络:网络链路的防火墙/安全组/网段问题,是本地外场景的主要诱因,需按场景针对性放行端口、确保网络连通。
遵循以上流程和解决方案,能快速定位并解决 99% 以上的 Net::ERR_CONNECTION_REFUSED 问题,同时养成「先验证服务端,再检查前端,最后排查网络」的排查思维,后续遇到同类网络连接问题,也能高效解决。
相关免费在线工具
- Keycode 信息
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具,Keycode 信息在线工具,online
- Escape 与 Native 编解码
JavaScript 字符串转义/反转义;Java 风格 \uXXXX(Native2Ascii)编码与解码。 在线工具,Escape 与 Native 编解码在线工具,online
- JavaScript / HTML 格式化
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具,JavaScript / HTML 格式化在线工具,online
- JavaScript 压缩与混淆
Terser 压缩、变量名混淆,或 javascript-obfuscator 高强度混淆(体积会增大)。 在线工具,JavaScript 压缩与混淆在线工具,online
- Base64 字符串编码/解码
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online
- Base64 文件转换器
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online