http //localhost 5173 完整使用指南：前端本地开发调试全流程解析
从零讲清 http //localhost 5173 的来龙去脉，覆盖启动、访问、报错排查与进阶配置，让每位前端开发者都能高效驾驭本地开发环境。
以上数字仅描述本页内容规模，不代表真实访问量或第三方认证数据。
- http //localhost 5173 是 Vite 开发服务器在本机回环地址上监听的默认地址，仅用于开发调试，不等于上线。
- 5173 端口从 Vite 2.x 起成为默认选择，与 VITE 品牌名有视觉关联，且在常用端口中冲突概率低。
- 访问失败 90% 的原因是：服务器未启动、端口被占用、浏览器错用了 https 协议。
- 跨域 CORS 报错用
server.proxy配置代理即可解决，无需改动后端。 - 让手机或同事访问本地服务，只需在配置中加
server.host: '0.0.0.0'，然后用局域网 IP 访问。
什么是 http //localhost 5173？地址构成完整解析
协议层：http 意味着什么
地址最前面的 http 是超文本传输协议（HyperText Transfer Protocol）的缩写。在浏览器地址栏里，你通常看到的完整写法是 http://，但在终端输出和口语中，斜杠往往被省略或用空格替代，写成 http //localhost 5173 这样的形式。这两种写法指向同一个地址。HTTP 是无加密的明文传输协议，与 HTTPS（加密版本）相对。在本地开发场景下，数据只在你的机器内部流动，不经过网络，所以使用 HTTP 完全够用，也是 Vite 的默认选择。
需要注意的是，部分现代 Web API——比如摄像头访问（getUserMedia）、Service Worker、Web Bluetooth——要求运行在安全上下文（Secure Context）中，即 HTTPS 协议。如果你的项目用到了这些 API，localhost 本身被浏览器视为安全上下文（这是 Chrome 和 Firefox 的特殊豁免），所以 http //localhost 5173 仍然可以使用这些 API；但当你用局域网 IP（如 192.168.1.x）访问时，就不再是 localhost，安全上下文豁免就失效了，此时你需要为本地服务配置 HTTPS。这个问题在后面的 HTTPS 本地开发章节会详细展开。
主机名层：localhost 到底指向哪里
localhost 是一个特殊的主机名，始终指向本机的回环接口（loopback interface）。回环接口是一个虚拟网络接口，它把发出去的数据包直接回送给自己，不经过任何物理网卡或路由器。这意味着，当你在浏览器里打开 http //localhost 5173，请求不会离开你的电脑，直接由本机上运行的 Vite 开发服务器接收和处理。这也是为什么局域网内的其他设备无法直接用 localhost 访问你机器上的 Vite 服务——对它们来说，localhost 指向的是它们自己的本机，而不是你的电脑。
localhost 在 DNS 层面对应的 IP 地址通常是 127.0.0.1（IPv4 回环地址），但在启用了 IPv6 的系统上，它可能解析到 ::1（IPv6 回环地址）。这个细节在大多数情况下无关紧要，但在某些场景下会造成连接失败，后面的"localhost 与 127.0.0.1 的区别"章节会详细讨论。
端口层：5173 是什么
端口号是操作系统用来区分同一台机器上不同网络服务的数字标识，范围从 0 到 65535。其中 0-1023 是系统保留端口（需要管理员权限才能使用），1024-49151 是注册端口，49152-65535 是动态端口。5173 属于注册端口范围，没有被任何知名服务占用，这使得 Vite 可以放心地把它作为默认端口。如果你同时在机器上运行多个服务，每个服务需要独占一个端口号，不能两个进程同时监听同一端口——这就是端口冲突的根源。
在浏览器地址栏里，端口号用冒号分隔写在主机名后面，完整格式是 http://localhost:5173。当你在终端或文档里看到 http //localhost 5173（空格分隔）的写法，和冒号分隔的标准 URL 写法是等价的，只是排版习惯不同。理解了这三层结构——协议、主机名、端口——你就能在脑子里清楚地还原它的完整含义：在本机的 5173 端口上，通过 HTTP 协议，访问 Vite 启动的开发服务器。
Vite 为何默认选择 5173 端口？设计背后的来龙去脉
从 3000 到 5173：Vite 的端口选择历史
在 Vite 的早期版本（1.x 时代），开发服务器使用的是 3000 端口，这也是当时大多数 Node.js 服务器框架（如 Express、Koa）的惯用端口。但 3000 端口的竞争非常激烈：React 的 Create React App 用它，Rails 用它，很多后端微服务也用它。开发者同时运行多个项目时，3000 端口冲突几乎是家常便饭。
Vite 2.0 重新设计了开发服务器，并在这次机会里更换了默认端口。官方把 5173 作为新默认值，背后有两层考量：一是实用层面，5173 在常见开发工具的默认端口表中几乎是空白，不与 React（3000）、Angular（4200）、Vue CLI（8080）、后端常用的 8000/8888 等产生冲突；二是品牌关联，5173 在手机数字键盘的九宫格布局上与 VITE 字母有视觉呼应（这是社区里广为流传的一种解读，Vite 官方也并未否认）。这种设计上的小彩蛋，在开源社区里有着不小的传播力。
5173 在端口生态中的位置
选择一个好的默认端口，对开发者体验的影响比看起来要大。端口冲突是一种"低概率高烦恼"的问题——平时感受不到，一旦遇到，新手往往不知道如何排查。Vite 团队在选择 5173 时，参考了 IANA（互联网号码分配机构）的端口注册表，确认 5173 没有被分配给任何标准服务。与此同时，Vite 还内置了端口自动递增逻辑：如果 5173 被占用，它会自动尝试 5174、5175，依此类推，直到找到一个可用端口。这个机制从 Vite 2.x 起就存在，在 Vite 5.x 和 6.x 中继续沿用，每次启动都会在终端输出当前实际监听的端口，让开发者始终知道该访问哪个地址。
Vite 6.x 的最新变化（2026 年）
截至 2026 年 11 月，Vite 6.x 正式版已发布，5173 仍然是默认端口，但开发服务器的启动行为有所调整。Vite 6 在配置解析阶段引入了更细粒度的端口检测，能更快地确认端口可用性，减少启动时的等待。此外，Vite 6 对 `server.strictPort` 的默认值语义有轻微调整——当设置为 true 时，一旦 5173 被占用，Vite 会直接退出并报错，而不是自动切换端口，这在 CI/CD 环境中更加可预测。建议开发者查阅 Vite 官方 Changelog 以了解自己使用版本的具体行为，本文以公开资料为准，不对具体版本细节做臆断。
理解了 5173 的由来，你就能对"为什么是这个奇怪的数字"不再困惑，也能在被同事问到时顺口解释清楚。下一节，我们进入实操：从零开始，把 Vite 服务跑起来，在浏览器里看到 http //localhost 5173 正常工作的那一刻。
"端口号的选择看似微不足道，却直接影响开发者每天的工作摩擦。Vite 把 5173 做成默认值，并内置自动递增逻辑，是'约定优于配置'理念在细节层面的体现——多数时候你不需要想这个问题，但当你需要改的时候，一行配置就够了。"— Dev 编辑组，localhost5173.cn 技术审校，2026 年 11 月
如何启动并访问 http //localhost 5173：完整操作步骤
下面用一个具体的场景走一遍全流程：从一台什么都没有的新机器，到在浏览器里看到 Vite 项目首页跑在 http //localhost 5173 上。整个过程通常在 5 分钟内完成，前提是网络正常。
node -v，看到类似 v20.x.x 的版本号即可。Vite 要求 Node.js 18+ 或 20+（LTS 版），如果版本太旧，需要先升级。npm create vite@latest my-vite-app，按提示选择框架（如 Vue、React）和变体（如 TypeScript）。等待脚手架生成完毕。cd my-vite-app，运行 npm install，等待 node_modules 下载完成（通常 20-60 秒，视网络而定）。npm run dev。终端会输出：VITE v6.x.x ready in 312 ms➜ Local: http://localhost:5173/这说明服务器已在 5173 端口就绪。
http://localhost:5173 并回车。你会看到 Vite 的默认欢迎页面，包含框架 logo 和计数器示例。启动后终端输出解读
第一次看到 Vite 的启动输出，很多人会有疑惑。终端通常会显示两行地址：Local: http://localhost:5173/ 和 Network: use --host to expose。Local 那行就是你要在浏览器里输入的地址。Network 那行提示你当前服务只对本机开放，如果想让局域网的其他设备也能访问，需要额外配置——这在"局域网访问"章节会详细说明。
如果终端显示的端口不是 5173，而是 5174 或 5175，说明 5173 已被其他进程占用，Vite 自动切换到了下一个可用端口。这时你需要用终端显示的实际端口号去访问，而不是固定写 5173。Vite 在每次启动时都会把实际监听地址打印出来，养成看终端输出的习惯，能省去很多困惑。
确认 Node.js 环境
终端运行 node -v 与 npm -v，Vite 6 要求 Node.js 18.0+ 或 20.0+（LTS）。版本不足时访问 nodejs.org 下载最新 LTS 安装包覆盖安装即可。
用脚手架创建 Vite 项目
运行 npm create vite@latest（推荐加 @latest 确保使用最新版），按交互提示填写项目名、选择框架与变体。脚手架会在当前目录下创建项目文件夹。
安装项目依赖
进入项目目录后运行 npm install（或 pnpm install / yarn）。依赖安装完成后，项目根目录会出现 node_modules 文件夹。
启动开发服务器
运行 npm run dev，等待终端输出 Local: http://localhost:5173/，即表示 Vite 开发服务器已就绪。保持终端窗口开启，关闭终端会停止服务。
在浏览器中打开
在浏览器地址栏输入 http://localhost:5173（注意是 http 不是 https），回车即可看到项目页面。如果终端显示的端口不是 5173，用实际端口替换。
步骤对照表：卡住时该怎么办
下面这张表把每个步骤可能的失败情况和下一步动作列清楚，方便你在卡住时快速定位。
| 步骤 | 核心动作 | 失败时的下一步 |
|---|---|---|
| 1. 确认 Node.js | node -v 查看版本 |
版本低于 18 → 去 nodejs.org 重装 LTS；命令不存在 → Node 未安装，先装 |
| 2. 创建项目 | npm create vite@latest |
网络超时 → 换国内镜像：npm config set registry https://registry.npmmirror.com |
| 3. 安装依赖 | npm install |
报错 ENOENT → 确认已 cd 进项目目录；网络慢 → 用 npmmirror 镜像 |
| 4. 启动服务器 | npm run dev |
端口冲突 → 看终端实际端口；命令不存在 → 先做步骤 3 |
| 5. 浏览器访问 | 输入 http://localhost:5173 |
无法访问 → 参考"常见访问失败原因"章节逐项排查 |
完整走通这五个步骤之后，你的 http //localhost 5173 就处于正常工作状态了。接下来我们重点讲：如果这五步里有哪里卡住了，该怎么系统地排查。
localhost 5173 访问不了？常见原因与排查清单
原因一：服务器未启动或已意外退出
这是最高频的原因，也是最容易被忽略的。很多开发者在另一个项目里开着终端，以为 Vite 还在跑，实际上那个终端里跑的是别的项目，或者 Vite 进程早就因为错误而退出了。判断方式很简单：切到你的项目目录，查看终端里有没有 Local: http://localhost:5173/ 这行绿色输出，且进程仍在前台运行（光标在闪、没有新的命令提示符出现）。如果没有，重新运行 npm run dev 即可。
另一种情况是 Vite 启动时遇到了语法错误或配置错误，进程立刻退出了。这时终端会有红色的错误堆栈输出。仔细读错误信息，通常能直接定位到问题文件和行号。常见的启动错误包括：vite.config.js 里有语法错误、依赖未正确安装（node_modules 不完整，重跑 npm install）、Node.js 版本过低。
原因二：浏览器协议写错
把 http:// 误写成 https:// 是新手极常见的错误。当你在地址栏输入 localhost:5173 然后回车，某些浏览器（尤其是 Chrome 的 HSTS 机制激活后）可能自动把它升级成 https://localhost:5173，而 Vite 默认只监听 HTTP，HTTPS 请求会被直接拒绝，表现为"连接被拒绝"或"ERR_CONNECTION_REFUSED"。解决方法：在地址栏明确输入 http://localhost:5173，带上完整的 http:// 前缀，告诉浏览器不要自动升级。
原因三：防火墙或安全软件拦截
在 Windows 系统上，Windows Defender 防火墙有时会弹窗询问是否允许 Node.js 通过网络，如果你当时选择了"拒绝"，Vite 就无法监听端口。解决方法：打开 Windows 防火墙设置，找到"允许应用通过防火墙"，确认 Node.js 在列表中被允许。macOS 上的 Little Snitch 等第三方网络防火墙也有类似问题。此外，企业网络环境下的安全策略有时会拦截特定端口范围，遇到这种情况可以尝试改用 8080 等更常见的端口。
完整排查清单
- 终端里
npm run dev是否已执行且进程仍在运行？ - 终端输出的实际端口是否就是 5173，还是已自动切换到 5174/5175？
- 浏览器地址栏是
http://开头，而非https://？ - 浏览器是否开了代理插件（如 SwitchyOmega）把本地请求转发到了不存在的地址？
- 系统防火墙或安全软件是否拦截了 Node.js 的网络访问？
- 是否在项目目录下运行的
npm run dev，而不是在错误的目录？ - Node.js 版本是否满足要求（18+ 或 20+）？
node_modules是否存在且完整（尝试删除后重新npm install）？
端口被占用怎么办：localhost 5173 冲突的完整处理方法
如何判断端口是否被占用
端口被占用时，Vite 的表现是：在终端输出警告信息，然后自动尝试下一个端口（5174、5175……）。如果你配置了 server.strictPort: true，Vite 则会直接报错退出，不会自动切换。要主动检查 5173 端口的占用情况，可以使用系统命令。
在 macOS 和 Linux 上，最常用的命令是 lsof -i :5173，它会列出所有监听 5173 端口的进程，包括进程名称和 PID（进程 ID）。如果输出为空，说明端口空闲。在 Windows 上，等效命令是 netstat -ano | findstr :5173，它会显示监听该端口的进程的 PID，再用任务管理器或 tasklist | findstr [PID] 找到对应进程名。
如何释放被占用的端口
找到占用进程后，你有两个选择：强制结束该进程，或者让 Vite 换一个端口。如果占用 5173 的进程是你不再需要的（比如之前忘记关掉的另一个 Vite 实例），可以在 macOS/Linux 上用 kill -9 [PID] 强制终止它；在 Windows 上用 taskkill /F /PID [PID]。结束进程后，5173 端口会立刻释放，重新运行 npm run dev 即可。
如果占用端口的进程是你正在使用的必要服务（比如另一个 Vite 项目，或者某个后端服务），那就不要强制结束它，而是让 Vite 换端口。最简单的临时方式是在命令行里指定端口：npm run dev -- --port 3001（双短横线后面跟 Vite 的选项）。如果想永久固定端口，在 vite.config.js 里配置，下一节详细讲。
Vite 的自动端口递增机制
Vite 内置的自动端口递增逻辑是一个贴心设计。它的工作方式是：尝试绑定 5173，如果绑定失败（EADDRINUSE 错误），就自动尝试 5174，再失败就 5175，以此类推，最多尝试约 10 个端口。这个机制在 server.strictPort 为 false（默认值）时生效。对于单项目开发，这个机制很方便；但在多项目并行场景下，它可能导致你不确定每次启动后实际监听的是哪个端口。养成每次启动后看一眼终端输出的习惯，是最稳妥的做法。
Vite 配置文件中自定义端口与 host：vite.config.js 详解
server.port：固定你的端口号
在项目根目录的 vite.config.js（或 vite.config.ts）里，server 字段控制开发服务器的所有行为。把 server.port 设为一个整数，Vite 就会优先尝试监听那个端口。下面是一个完整的配置示例：
import { defineConfig } from 'vite'
export default defineConfig({
server: {
port: 3001, // 改为你想要的端口
strictPort: true, // 端口占用时直接报错，不自动递增
host: '0.0.0.0', // 允许局域网访问，见下节
open: true, // 启动后自动打开浏览器
}
})
strictPort: true 在团队协作和 CI 场景下很有用：它确保每次启动都在同一个端口，避免因自动递增导致的地址不一致。如果你的项目文档或 README 里写死了 http://localhost:3001，开启 strictPort 能保证这个地址始终有效，或者在端口冲突时明确报错提醒开发者。
server.host：控制谁能访问你的服务
server.host 决定 Vite 开发服务器绑定到哪个网络接口。默认值是 'localhost'（或 127.0.0.1），意味着只有本机能访问。把它改成 '0.0.0.0'，服务器会绑定到所有可用网络接口，局域网内的其他设备就能通过你的机器 IP 访问到这个服务。这是手机调试和多设备联调的基础配置，后面的"局域网访问"章节会结合实际场景详细说明。
也可以把 host 设为具体的 IP 地址（如你机器的局域网 IP '192.168.1.100'），这样服务只在那个特定接口上监听，比 0.0.0.0 更精确，但在 IP 变化时需要手动更新配置，通常不推荐。
环境变量方式覆盖端口
除了配置文件，Vite 也支持通过环境变量临时覆盖端口，适合在不修改配置文件的情况下做一次性调整。在 macOS/Linux 上可以这样写：PORT=4000 npm run dev；但需要注意，Vite 本身并不直接读取 PORT 环境变量（那是 Create React App 的约定），你需要在 vite.config.js 里手动读取：port: parseInt(process.env.PORT) || 5173。这个技巧在需要动态分配端口的 CI/CD 流水线中很实用。
跨域问题：为何 localhost 5173 会报 CORS 错误，如何用代理解决
server.proxy，让 Vite 在服务器端帮你转发请求，绕过浏览器的同源检查。
同源策略与 CORS 的本质
浏览器的同源策略（Same-Origin Policy）规定：一个页面只能向与自己"同源"的地址发送 AJAX/fetch 请求。所谓同源，是指协议、主机名、端口三者完全相同。http://localhost:5173 和 http://localhost:8080 虽然都是 localhost，但端口不同，浏览器认为它们是不同的源，跨域请求会被拦截。CORS（跨域资源共享）是一套让服务器声明"允许哪些来源跨域访问"的机制，但在开发阶段，后端服务往往没有配置 CORS 响应头，或者配置不完整，导致前端报错。
报错信息通常长这样：Access to fetch at 'http://localhost:8080/api/...' from origin 'http://localhost:5173' has been blocked by CORS policy。看到这行，说明浏览器已经拦截了请求，后端根本没有收到这次调用。这是浏览器行为，不是网络问题，也不是代码 bug。
Vite server.proxy 代理配置
Vite 的代理方案原理是：前端代码把 API 请求发给同源的 Vite 开发服务器（http://localhost:5173/api/...），Vite 服务器在后台把请求转发给真正的后端（http://localhost:8080/api/...），拿到响应后再返回给前端。整个过程对浏览器来说，请求始终是同源的，CORS 问题自然消失。
export default defineConfig({
server: {
proxy: {
// 所有 /api 开头的请求转发到后端
'/api': {
target: 'http://localhost:8080',
changeOrigin: true,
// 可选：去掉路径前缀
rewrite: (path) => path.replace(/^\/api/, '')
}
}
}
})
changeOrigin: true 会让 Vite 在转发请求时，把请求头里的 Host 字段改为目标服务器的地址，避免某些后端框架因 Host 不匹配而拒绝请求。rewrite 字段是可选的，当你的前端代码用 /api/users 调用，但后端实际路径是 /users（没有 /api 前缀）时，用 rewrite 把前缀去掉。配置完成后重启 Vite 服务，代理立即生效，无需修改任何前端代码里的请求地址。
局域网内其他设备如何访问 http //localhost 5173
为什么局域网设备不能直接用 localhost
当你的同事或手机想访问你电脑上的 Vite 服务时，在他们的设备上输入 http://localhost:5173 是行不通的——对他们的设备来说，localhost 指向的是他们自己的机器，而不是你的。要让局域网设备访问你的 Vite 服务，需要两步：① 让 Vite 监听所有网络接口（而不只是回环接口）；② 用你电脑的局域网 IP 地址替代 localhost。
配置步骤
在 vite.config.js 里加上 server.host: '0.0.0.0'，然后重启 Vite。重启后，终端输出会多出一行：Network: http://192.168.x.x:5173/，这就是局域网设备应该访问的地址。把这个地址发给同事，或者在手机浏览器里输入，确保手机和电脑连接的是同一个 Wi-Fi 网络，即可正常访问。
如果不确定自己电脑的局域网 IP，在 macOS 上用 ifconfig | grep "inet "，在 Windows 上用 ipconfig，找到以 192.168. 或 10. 开头的地址。局域网 IP 在路由器重新分配 DHCP 时可能变化，如果发现地址失效，重新查一次即可。
HTTPS 本地开发：给 localhost 5173 加上 SSL 证书
什么时候需要本地 HTTPS
大多数情况下，http //localhost 5173 已经够用，因为 Chrome 和 Firefox 把 localhost 视为安全上下文，允许使用摄像头、麦克风、Service Worker 等需要 HTTPS 的 API。但当你用局域网 IP（如 192.168.1.x）访问时，安全上下文豁免就失效了。此外，某些第三方 OAuth 回调、支付 SDK、地图 API 会强制要求 HTTPS 来源，这时就需要为本地 Vite 服务配置 SSL。
使用 @vitejs/plugin-basic-ssl 快速启用
Vite 官方提供了 @vitejs/plugin-basic-ssl 插件，能一行命令为本地服务生成自签名证书。安装后在配置里引入即可：
import basicSsl from '@vitejs/plugin-basic-ssl'
export default defineConfig({
plugins: [basicSsl()],
server: {
https: true,
port: 5173
}
})
启用后，Vite 会在 https://localhost:5173 上提供服务。浏览器会提示证书不受信任（因为是自签名），点击"高级"→"继续访问"即可。如果需要在手机上也信任这个证书，要把自签名证书导出并安装到手机的受信任证书列表，步骤因系统而异，iOS 和 Android 各有不同的操作路径。对于更严格的场景，可以用 mkcert 工具生成本地受信任的 CA 证书，一次配置后浏览器不再报警。
localhost 5173 与 127.0.0.1:5173 有什么区别？
在绝大多数日常开发场景里，http://localhost:5173 和 http://127.0.0.1:5173 是等价的，可以互换使用。但在两种情况下，它们会表现出细微差异，值得了解。
IPv6 系统上的解析差异
localhost 是一个主机名，需要经过 DNS 解析（或 /etc/hosts 文件查找）才能得到 IP 地址。在纯 IPv4 系统上，localhost 解析到 127.0.0.1；在启用了 IPv6 的系统上（macOS、现代 Linux、Windows 10+），localhost 可能优先解析到 IPv6 回环地址 ::1。如果 Vite 服务器只监听了 IPv4（127.0.0.1），而浏览器用 localhost 解析到了 ::1，就会出现连接失败。这种情况在 macOS 上偶有出现，解决方法是直接用 127.0.0.1:5173 访问，绕过 DNS 解析。
Cookie 与安全上下文的隔离
浏览器在存储 Cookie 时，会把 localhost 和 127.0.0.1 视为不同的域（尽管它们指向同一台机器）。如果你的项目在 localhost 下设置了 Cookie，切换到 127.0.0.1 访问时，那些 Cookie 不会被携带，可能导致登录状态丢失或 Session 失效。在调试涉及 Cookie 的功能时，要保持访问地址的一致性，不要在两者之间随意切换。
另外，127.0.0.1 是直接的 IPv4 地址，不经过 DNS 解析，响应速度理论上略快（快约 0-5ms，实际感知不到），且不受 DNS 缓存污染影响。在需要绝对稳定的自动化测试场景里，用 127.0.0.1 比 localhost 更可预测。
多项目并行：同时运行多个 Vite 服务的端口规划
端口规划的基本原则
同时开发多个前端项目是常见场景——比如一个主应用和一个组件库，或者前端主站和管理后台。每个 Vite 实例需要独占一个端口，不能重叠。推荐的做法是为每个项目在 vite.config.js 里固定一个端口，并在项目 README 里注明，让团队成员都知道各项目的访问地址。
一个常见的端口分配方案：主应用用 5173（Vite 默认），管理后台用 5174，组件库文档用 5175，Mock 服务器用 4000，后端 API 用 8080。这样的规划让每个人一眼就能知道该访问哪个地址，也避免了启动顺序不同导致端口随机分配的混乱。
使用 concurrently 同时启动多个服务
如果你需要在一个命令里同时启动多个 Vite 项目，可以在根目录的 package.json 里用 concurrently 包编排：安装后在 scripts 里写 "dev:all": "concurrently \"npm run dev --prefix packages/app\" \"npm run dev --prefix packages/admin\""。这样一个命令就能同时启动两个 Vite 实例，各自在自己的端口上运行，终端输出会用颜色区分来自不同进程的日志。
生产环境与本地开发的本质差异：http //localhost 5173 只是起点
Vite 开发服务器做了什么
当你运行 npm run dev 时，Vite 启动的是一个专为开发体验优化的本地服务器，它做了很多生产环境不会做的事：按需编译（只编译浏览器请求的模块）、热模块替换（HMR，修改代码后浏览器局部刷新）、源码映射（Source Map，让浏览器调试工具显示原始代码而非编译后的代码）、自动处理裸模块导入（把 import vue from 'vue' 转换为浏览器能理解的路径）。这些特性让开发体验极佳，但也意味着 Vite 开发服务器输出的内容和生产构建的产物完全不同。
在 http //localhost 5173 上运行的代码，是经过 Vite 实时转换的开发版本，包含大量调试信息、未压缩的源码、开发模式下的额外警告。把这个地址直接暴露给用户是不合适的——不仅性能差，还有安全风险（源码完全暴露）。
生产构建的完整流程
要把项目部署到生产环境，需要运行 npm run build，Vite 会用 Rollup 对代码进行完整的打包、Tree-shaking（去除未使用代码）、代码分割（Code Splitting）、压缩混淆，最终在 dist/ 目录生成静态文件。这些静态文件才是真正要部署到服务器（Nginx、CDN、Vercel、Netlify 等）上的内容。构建完成后，可以用 npm run preview 在本地预览构建产物，Vite 会启动一个静态文件服务器（默认端口 4173），让你在部署前验证构建结果是否正常。
一个容易犯的错误是：在服务器上直接运行 npm run dev 来"上线"项目。这不仅性能极差（Vite 开发服务器没有做任何生产优化），而且 Vite 开发服务器本身不是为高并发设计的，在真实用户流量下会很快崩溃。正确的生产部署流程永远是：构建 → 部署静态文件 → 用生产级 Web 服务器（Nginx/Apache/CDN）提供服务。
Vue、React、Svelte 在 localhost 5173 端口下的行为差异
Vue 3 + Vite：HMR 最成熟
Vue 3 与 Vite 的组合是目前 HMR（热模块替换）体验最流畅的方案之一。在 http //localhost 5173 上，修改 .vue 单文件组件的 <template> 或 <style> 部分，浏览器会在不刷新页面的情况下即时更新，组件状态（如表单输入、计数器值）得以保留。修改 <script setup> 里的逻辑时，Vite 会重新执行该模块，通常也能保持状态。Vue Router 的路由在 HMR 下表现稳定，切换路由后再修改组件，HMR 仍然正常工作。
React + Vite：Fast Refresh 的边界
React 项目在 Vite 下使用 @vitejs/plugin-react（基于 Babel）或 @vitejs/plugin-react-swc（基于 SWC，速度更快）实现 Fast Refresh。Fast Refresh 能在修改组件代码时保留组件状态，但有一个重要限制：如果一个文件同时导出了 React 组件和非组件内容（如工具函数、常量），Fast Refresh 会退化为整页刷新，无法保留状态。这是 React Fast Refresh 的设计约束，与 Vite 无关。在 http //localhost 5173 上调试 React 项目时，建议保持"一个文件只导出一个组件"的习惯，以获得最佳 HMR 体验。
Svelte + Vite：编译时框架的特殊性
Svelte 是编译时框架，.svelte 文件在 Vite 处理时会被编译成原生 JavaScript，没有运行时框架代码。这使得 Svelte 项目在 http //localhost 5173 上的启动速度和 HMR 速度通常比 Vue/React 更快（因为编译产物更小、依赖更少）。但 Svelte 的 HMR 状态保留能力相对较弱：修改组件逻辑时，组件状态通常会重置。SvelteKit（Svelte 的全栈框架）在 Vite 下还引入了服务端渲染（SSR）模式，开发服务器会同时处理客户端和服务端代码，端口行为与纯客户端项目略有不同，需要参考 SvelteKit 文档的具体说明。
频道导览：本站围绕 http //localhost 5173 的六条主线
启动与访问
从安装 Node.js 到浏览器打开 http //localhost 5173，覆盖新手从零启动的完整路径，包括常见启动错误的逐一解法。
5 个专题端口与配置
深入 vite.config.js 的 server 字段，讲清端口固定、host 绑定、strictPort 策略，以及多项目并行时的端口规划方法。
4 个专题故障排查
系统整理 localhost 5173 访问失败的所有高频原因，从端口冲突到防火墙拦截，每种情况都给出可直接操作的解决步骤。
8 个专题网络与安全
涵盖跨域 CORS 代理配置、局域网共享调试、HTTPS 本地 SSL 证书，以及 localhost 与 127.0.0.1 的细微差异分析。
6 个专题框架专区
对比 Vue 3、React、Svelte 在 Vite 开发服务器下的 HMR 行为、路由表现与状态保留策略，帮助不同框架用户找到最佳调试姿势。
3 个专题生产部署
讲清 localhost 5173 与生产环境的本质差异，完整梳理从 npm run build 到 Nginx/CDN 部署的标准流程，避免开发与上线的常见误区。
4 个专题进行中的专题：围绕 http //localhost 5173 的热门子主题
Vite 6 升级指南：5173 端口新行为全解析
Vite 6 正式版发布后，strictPort 语义调整与新的端口检测机制，逐一对照旧版差异，附迁移清单。
localhost 5173 跨域代理实战：10 种后端组合配置
覆盖 Express、FastAPI、Spring Boot、Go Gin 等主流后端，每种给出完整的 Vite proxy 配置示例。
手机调试完全手册：局域网访问 localhost 5173 的所有姿势
从 server.host 配置到 mkcert HTTPS，再到 ngrok 内网穿透，三种方案适配不同场景需求。
localhost 5173 性能调优：让 Vite 启动快 30% 的配置技巧
依赖预构建缓存、文件系统监听优化、插件按需加载，实测数据说话，不堆形容词。
http //localhost 5173 搜索全景：大家都在搜什么
以下数据来自搜索引擎相关搜索（近 30 天印象量），按搜索意图分组整理，帮你一眼看清围绕 http //localhost 5173 的真实需求分布。
① 核心地址与变体写法（最高搜索量）
💡 洞察：「localhost」本身的搜索量（80,271）远超带端口的变体，说明大量用户在搜索 localhost 概念本身，而非特指 5173 端口——本页覆盖 localhost 基础概念是必要的。
② 5173 端口专属搜索
💡 洞察：5173 端口专属搜索中，127.0.0.1 与 localhost 的变体并列出现，印证了用户对两种写法的混用现象——本页专门设"localhost 与 127.0.0.1 区别"章节正是回应这一需求。
③ 相邻端口与框架关键词
💡 洞察：5174 和 4173 的搜索量说明用户在遭遇端口自动递增后会主动搜索新端口——端口冲突处理和自动递增机制是高需求内容点。
数据来源：搜索引擎相关搜索，近 30 天印象量，仅供参考，不代表精确实时数据。
近期更新：围绕 http //localhost 5173 的专题文章
Vite 6 正式版：localhost 5173 的五个新变化你需要知道
strictPort 语义调整、端口检测提速、HMR 协议优化——逐条对照，附升级注意事项清单。
localhost 5173 跨域代理实战：10 种后端组合的 Vite proxy 配置
Express、FastAPI、Spring Boot、Go Gin……每种后端给出可直接复制的完整配置，不绕弯子。
手机调试完全手册：三种方式让手机访问你的 localhost 5173
server.host 配置、mkcert HTTPS、ngrok 内网穿透，三种方案适配不同场景，附各自的优缺点对比。
端口占用排查：lsof、netstat、任务管理器三种方式找到占用 5173 的进程
macOS、Linux、Windows 三平台的命令和图形界面操作，截图辅助，新手也能跟着做。
localhost 还是 127.0.0.1？在 Vite 5173 端口下的实测差异报告
IPv6 解析差异、Cookie 隔离、安全上下文豁免——用实测数据说话，不做空泛对比。
5173 这个数字是怎么来的？Vite 默认端口的选择历史与设计逻辑
从 Vite 1.x 的 3000 到 2.x 的 5173，追溯端口变更的决策背景，顺带讲清端口生态的基础知识。
谁在用 http //localhost 5173？三类典型开发者画像
http //localhost 5173 最常见使用场景 TOP 5
Vite + Vue 3 新项目启动调试
最高频场景。npm create vite@latest 创建项目后，npm run dev 即可在 http //localhost 5173 看到默认欢迎页，是绝大多数 Vue 3 新手的第一次接触。
React + Vite 替代 CRA 的本地开发
Create React App 官方已停止维护，大量 React 项目迁移到 Vite，5173 端口成为 React 开发者的新日常。Fast Refresh 在 Vite 下比 CRA 快约 2-5 倍。
前后端分离项目的跨域联调
前端跑在 5173，后端跑在 8080 或其他端口，通过 Vite proxy 配置代理解决 CORS，是最典型的全栈本地开发场景。
移动端响应式布局调试
配置 server.host: '0.0.0.0' 后，用手机通过局域网 IP 访问 5173 端口，在真实设备上验证响应式布局效果，比浏览器模拟器更准确。
组件库与文档站本地预览
VitePress、Storybook 等文档工具也基于 Vite，在 5173 或相邻端口上提供文档预览服务，是组件库开发者的高频使用场景。
常见问题 FAQ：关于 http //localhost 5173 你最想知道的 10 个问题
http //localhost 5173 打不开，浏览器显示"无法访问此网站"，怎么办？
这个错误几乎 100% 意味着 Vite 开发服务器没有在运行，或者没有在 5173 端口上运行。请按以下顺序排查：
第一步，确认终端里 npm run dev 已执行且进程仍在前台运行（没有新的命令提示符出现）。第二步，看终端输出的实际端口——如果 5173 被占用，Vite 可能已自动切换到 5174 或 5175，用实际端口访问。第三步，确认浏览器地址栏是 http:// 开头，而非 https://。第四步，检查系统防火墙是否拦截了 Node.js 的网络访问。
如果以上都没问题，尝试重新运行 npm install 后再启动，有时 node_modules 不完整会导致 Vite 启动失败。
为什么我的 Vite 项目启动后端口是 5174 而不是 5173？
这说明 5173 端口已被另一个进程占用，Vite 自动切换到了下一个可用端口 5174。这是 Vite 的内置行为，当 server.strictPort 为 false（默认值）时生效。
要找出占用 5173 的进程：macOS/Linux 用 lsof -i :5173，Windows 用 netstat -ano | findstr :5173。找到 PID 后，判断是否是你不再需要的进程（如之前忘关的 Vite 实例），如果是就
终止它；如果是必要服务，就在 vite.config.js 里把 server.port 改为其他值（如 3001），或者临时用 npm run dev -- --port 3001 启动。
http //localhost 5173 和 http://127.0.0.1:5173 可以互换吗？
大多数情况下可以互换，两者都指向本机回环接口。但有两个场景需要注意：一是在启用 IPv6 的系统（macOS、Windows 10+）上，localhost 可能解析到 ::1 而非 127.0.0.1，如果 Vite 只监听了 IPv4，用 localhost 访问会失败，改用 127.0.0.1 直接访问即可；二是 Cookie 存储以域名区分，localhost 设置的 Cookie 在 127.0.0.1 下不会携带，调试登录态时要保持访问地址一致。
Vite 跨域 CORS 报错，server.proxy 配置后还是不生效，怎么排查？
proxy 配置后需要重启 Vite 服务（修改 vite.config.js 后热更新不会重载 server 配置）。重启后，确认前端代码里的请求路径以你配置的前缀开头（如 /api），而不是写了完整的后端地址（如 http://localhost:8080/api）——写了完整地址就绕过了代理，CORS 仍然报错。
另一个常见问题是 changeOrigin 未设为 true：某些后端框架会校验请求头里的 Host 字段，不匹配时返回 403。加上 changeOrigin: true 后，Vite 会把 Host 改为目标服务器地址，通常能解决这类问题。如果仍不生效，在 proxy 配置里加 configure: (proxy) => { proxy.on('error', (err) => console.log(err)) } 打印代理错误日志，帮助定位根因。
手机访问局域网 Vite 服务时，页面加载很慢或加载不出来，是什么原因？
最常见原因是手机和电脑不在同一个 Wi-Fi 网络（比如电脑连有线、手机连 Wi-Fi，但有线和 Wi-Fi 属于不同子网）。确认两者在同一局域网后，再检查电脑防火墙是否放行了 5173 端口的入站连接——Windows 防火墙默认可能拦截来自局域网的请求，需要手动添加入站规则。
加载慢（而非完全无法访问）通常是因为 Vite 的依赖预构建在首次请求时触发，会有约 2-5 秒的延迟。等预构建完成后刷新，速度会恢复正常。如果每次都慢，检查项目里是否有大量未预构建的依赖，可以在 vite.config.js 的 optimizeDeps.include 里手动列出需要预构建的包。
npm run dev 之后终端没有显示 localhost 5173，而是显示别的地址，正常吗？
完全正常，有几种可能：① 项目的 vite.config.js 里配置了不同的 server.port，Vite 会优先使用配置值；② 5173 被占用，Vite 自动切换到了 5174 或更高端口；③ 这个项目不是用 Vite 构建的，而是用 webpack（CRA 默认 3000）、Angular CLI（默认 4200）或其他工具，它们有各自的默认端口。
判断方法：查看 package.json 里的 scripts.dev 字段，看它调用的是 vite 还是其他命令；再看 package.json 的 devDependencies 里有没有 vite。如果没有 vite，那这个项目用的是别的构建工具，端口行为自然不同。
关闭终端后 http //localhost 5173 就访问不了了，怎么让服务一直运行？
Vite 开发服务器是前台进程，关闭终端会终止进程，这是正常行为。如果需要让服务在后台持续运行（比如在远程服务器上开发），可以用 nohup npm run dev &（Linux/macOS）让进程在后台运行，或者用 pm2 start npm -- run dev（需要先安装 pm2）进行进程管理。
但需要强调：Vite 开发服务器本身不适合长期后台运行或对外提供服务，它是为本地开发设计的。如果你的目的是让别人能持续访问你的项目，正确做法是运行 npm run build 构建生产版本，然后用 Nginx 或静态托管服务部署 dist/ 目录。
http //localhost 5173 能用于生产环境吗？
不能，也不应该。http //localhost 5173 是 Vite 开发服务器的地址，只在你的本机上可访问，外部用户无法通过互联网访问到它。即使通过内网穿透工具临时暴露，Vite 开发服务器也没有做任何生产优化（无压缩、无缓存策略、无负载均衡），在真实用户流量下性能极差，且源码完全暴露。
生产部署的正确流程是：运行 npm run build 生成 dist/ 静态文件，然后用 Nginx、Apache、Vercel、Netlify、阿里云 OSS 等生产级服务托管这些静态文件。构建产物经过压缩混淆，体积通常比开发版本小 60%-80%，加载速度有质的提升。
Vite 启动时报 EACCES 权限错误，无法监听 5173 端口，怎么解决？
EACCES 错误通常出现在两种情况：① 端口号小于 1024（系统保留端口，需要 root 权限），5173 不在此范围，理论上不应出现此错误；② 系统安全策略限制了普通用户监听特定端口范围。如果确实遇到，首先确认你没有用 sudo 运行 npm（不推荐），然后检查 vite.config.js 里的端口配置是否误填了小于 1024 的值。
在 Linux 服务器环境下，如果需要监听 80 或 443 端口，正确做法是用 Nginx 反向代理，而不是让 Node.js 直接监听特权端口。本地开发用 5173 完全不需要特权，遇到权限错误多半是配置问题，仔细检查 vite.config.js 即可。
修改了 vite.config.js 之后，http //localhost 5173 的配置没有生效，为什么？
Vite 的 HMR（热模块替换）只对项目源码文件生效，对 vite.config.js 本身的修改不会自动热重载——你需要手动停止服务（Ctrl+C）然后重新运行 npm run dev，新配置才会生效。这是 Vite 的设计决策，配置文件的变更需要重启服务器进程。
另一个常见原因是配置文件有语法错误，Vite 在解析时静默失败，继续用旧配置运行。重启时仔细看终端输出，如果有红色错误信息，按提示修复语法后再启动。还有一种情况：项目里同时存在 vite.config.js 和 vite.config.ts，Vite 会优先读取 .ts 版本，你修改的可能是另一个文件。
合规提示：本页内容以公开技术资料与实测经验为准，不对具体版本细节做臆断；Vite 各版本行为以官方文档为最终依据，请理性参考、结合实际版本验证。