端口与 localhost

原始素材：2-开发环境与工具/2.05-ports-localhost.md

这篇解决什么问题

当你执行 npm run dev，终端里出现：

Local: http://localhost:5173/

这短短一行里其实包含三个关键概念：

• http://：通信协议，决定浏览器和服务端用什么规则对话。
• localhost：目标地址，表示访问你自己的电脑。
• :5173：端口号，表示访问这台电脑上的哪一个服务。

理解端口和 localhost，可以帮你解决很多开发环境里的常见问题：

• 为什么 localhost:5173 能打开，手机却访问不了。
• 为什么启动项目时报 EADDRINUSE。
• 为什么前端 5173 请求后端 3000 会跨域。
• 为什么 127.0.0.1、localhost、0.0.0.0 不是一回事。
• 为什么数据库端口不能直接暴露到公网。

开发服务器是什么

开发服务器可以理解为一个运行在本机上的 HTTP 服务。它一直监听某个端口，等待浏览器请求。

以 Vite 为例：

浏览器请求 http://localhost:5173/
  -> Vite 开发服务器收到请求
  -> 即时编译 Vue / React / TypeScript / CSS
  -> 返回浏览器可执行的 HTML、JS、CSS

所以开发服务器不是简单的「打开文件」，它通常还负责：

• 本地 HTTP 服务。
• 即时代码编译。
• 模块解析。
• HMR 热更新。
• 静态资源返回。
• API 代理。

什么是端口

可以把一台电脑想象成一栋大楼：

• IP 地址是大楼地址，告诉你去哪台机器。
• 端口号是房间号，告诉你找这台机器上的哪个服务。

一台电脑可以同时运行多个网络服务：

端口的本质是操作系统用来区分网络服务的编号。客户端连到某台机器后，操作系统根据端口号把连接交给对应的进程。

端口范围

端口号是 0-65535 之间的整数，共 65536 个。

开发服务器常用 3000、5173、8000、8080，因为它们不需要管理员权限，也不容易和系统标准服务冲突。

常见端口速查

安全原则很简单：数据库、缓存、管理后台、SSH 等端口不要直接暴露到公网。生产环境应通过内网、安全组、防火墙、VPN、SSH 隧道或零信任访问控制来限制入口。

什么是 localhost

localhost 是一个特殊域名，表示「本机」。

当你访问：

http://localhost:3000

大致发生这些事：

1. 浏览器把 localhost 交给操作系统解析。
2. 操作系统把它解析为 127.0.0.1，通常不需要请求外部 DNS。
3. 数据包发往 127.0.0.1。
4. 操作系统通过环回接口（loopback interface）把数据包折回本机。
5. 监听在 3000 端口的程序收到请求并返回响应。

整个过程不经过路由器、不需要网线，也不需要联网。

localhost、127.0.0.1、::1、0.0.0.0

这几个地址经常被混淆。

关键区别：

• 访问 localhost / 127.0.0.1：只找自己这台电脑。
• 服务监听 localhost / 127.0.0.1：只有本机能访问。
• 服务监听 0.0.0.0：本机所有网络接口都接收连接，局域网设备可能访问到。

例如：

# 只允许本机访问
npm run dev -- --host localhost

# 允许局域网设备访问，适合手机调试
npm run dev -- --host 0.0.0.0

很多框架默认只监听 localhost。所以手机和电脑连着同一个 Wi-Fi，也不一定能访问你的开发服务。要用手机调试，通常需要监听 0.0.0.0，然后用电脑的局域网 IP 访问，例如：

http://192.168.1.23:5173

端口冲突

一个端口同一时刻只能被一个进程监听。如果你启动第二个服务监听同一个端口，就会看到类似错误：

Error: listen EADDRINUSE :::3000

EADDRINUSE 的意思是 address already in use，也就是这个地址和端口已经被占用。

常见原因：

• 上次的开发服务器没有关干净。
• 两个项目使用了同一个默认端口。
• 后台进程仍在运行。
• 系统服务或 Docker 容器占用了端口。

如何排查端口占用

macOS / Linux

查看谁占用 3000 端口：

lsof -i :3000

输出里通常能看到进程名和 PID。终止进程：

kill -9 <PID>

如果想看监听端口，也可以使用：

lsof -nP -iTCP -sTCP:LISTEN

Windows

查看谁占用 3000 端口：

netstat -ano | findstr :3000

根据 PID 终止进程：

taskkill /PID <PID> /F

端口冲突的处理策略

遇到端口冲突，一般有三种处理方式：

很多现代框架在端口被占用时会询问是否换端口。但如果前端、后端、OAuth 回调、WebSocket 地址已经写死，自动换端口可能会引出新的问题。

同源策略和跨域

浏览器的同源策略（Same-Origin Policy）规定：只有协议、域名、端口都一致，才算同源。

这也是前后端分离项目常见跨域问题的来源：

前端开发服务器: http://localhost:5173
后端 API 服务:  http://localhost:3000

端口不同，浏览器就认为它们不同源。

跨域的两种常见解决方案

方案一：后端配置 CORS

后端明确允许前端源访问：

// Express 示例
app.use(cors({
  origin: 'http://localhost:5173',
}));

适合后端可控、需要真实跨源访问的情况。

方案二：前端开发服务器代理

在开发环境中，让前端开发服务器转发 API 请求：

// vite.config.js
export default {
  server: {
    proxy: {
      '/api': 'http://localhost:3000',
    },
  },
};

浏览器请求的是：

http://localhost:5173/api/users

Vite 在服务端把请求转发给：

http://localhost:3000/api/users

浏览器只看到同源请求，所以不会触发跨域限制。

三类常见问题排查

1. 端口被占用

现象：

Error: listen EADDRINUSE :::3000

排查：

lsof -i :3000

处理：

• 杀掉旧进程。
• 换端口。
• 检查 Docker、IDE、后台任务是否还在运行。

2. 连接被拒绝

现象：

ERR_CONNECTION_REFUSED

常见原因：

• 服务没启动。
• 端口写错。
• 服务只监听 localhost，但你从局域网设备访问。
• 防火墙或安全软件阻止连接。

排查顺序：

1. 看终端服务是否启动成功。
2. 用 lsof -i :端口 或 netstat 确认监听。
3. 本机先访问 localhost:端口。
4. 局域网访问时确认服务监听 0.0.0.0。
5. 检查防火墙和安全组。

3. 跨域被拦截

现象：

Access to fetch at ... from origin ... has been blocked by CORS policy

排查：

• 看浏览器控制台错误。
• 看 Network 面板里的请求地址、状态码和响应头。
• 确认协议、域名、端口是否一致。
• 确认后端是否返回 Access-Control-Allow-Origin。
• 开发环境优先考虑配置代理。

排查口诀

遇到 localhost 问题，可以按这个顺序走：

服务是否启动
  -> 端口是否正确
  -> 监听地址是否正确
  -> 本机能否访问
  -> 局域网能否访问
  -> 是否跨域
  -> 是否被防火墙或代理拦截

不要一上来就猜跨域。很多问题其实是服务没启动、端口写错或监听地址不对。

名词对照表

小结

• 端口是同一台机器上区分不同服务的编号。
• localhost 是本机地址，通常解析到 127.0.0.1，请求不会离开本机。
• 0.0.0.0 是监听所有网络接口，常用于局域网调试，但要注意安全。
• EADDRINUSE 表示端口已经被占用。
• 浏览器同源由协议、域名、端口共同决定，端口不同也会跨域。
• 开发环境跨域通常用 CORS 或 dev server proxy 解决。