http //localhost 5173/ 完全指南：从启动原理到调试实战
以 Vite 生态为核心，系统拆解这一本地开发地址背后的运行机制。端口为什么是 5173？访问不了怎么排查？跨域怎么配？这里统统讲清楚。
http //localhost 5173/ 到底是什么？地址三段深度拆解
本文速览 · 一句话看懂
- 01http //localhost 5173/ 是 Vite 在你本机启动的开发服务器地址，只有你自己的浏览器能访问。
- 02地址由三段组成：协议（http）、主机名（localhost）、端口号（5173）。
- 035173 并非随机，是 Vite 团队精心选定、与 VITE 字母映射的品牌端口。
- 04访问不了的原因 90% 集中在：服务未启动、端口被占用、防火墙拦截三类。
- 05跨域问题通过 vite.config 的 server.proxy 配置即可彻底解决，无需改后端。
每次用 Vite 启动一个前端项目，终端里都会出现那行熟悉的提示：Local: http://localhost:5173/。很多刚入门的同学会直接把这个地址粘到浏览器里打开，看到页面跑起来就算完事，但这个地址里其实藏着不少值得搞清楚的工程细节。
协议段：为什么是 http 而不是 https
地址最前面的 http 是超文本传输协议（HyperText Transfer Protocol）的缩写，是浏览器与服务器之间传输数据的规则约定。本地开发默认用 http 而非 https，原因很直接：https 需要 SSL/TLS 证书，而在本机 localhost 环境里，自签名证书会导致浏览器报不安全警告，反而妨碍调试。现代浏览器对 localhost 域名有特殊豁免——即便是 http 协议，也会把它视为"安全上下文"（Secure Context），Service Worker、Camera API 等需要安全上下文的特性都能正常使用。如果你的业务场景确实需要本地 https（比如调试某些第三方 OAuth 回调），Vite 也提供了 @vitejs/plugin-basic-ssl 插件，一行配置即可开启本地自签名 https。
主机名段：localhost 是什么意思
localhost 是一个特殊的域名，它永远指向本机的回环地址（Loopback Address）。在 IPv4 中，这个地址是 127.0.0.1；在 IPv6 中是 ::1。"回环"的意思是，发往这个地址的网络请求不会真正离开你的计算机，而是在操作系统内部绕一圈回来。这意味着 localhost 是彻底私有的——外网无法访问，同一局域网里的其他设备也访问不到（除非你做了额外配置）。正是因为这个特性，开发环境运行在 localhost 上天然安全，不用担心外部访问。
值得注意的是，localhost 与 127.0.0.1 在 Vite 的配置里有时表现略有不同。部分系统在 /etc/hosts 文件里没有正确配置 localhost 到 127.0.0.1 的映射（某些 macOS 系统升级后偶发这个问题），导致浏览器解析 localhost 时走了 DNS 查询、反而变慢甚至失败。遇到这种情况，直接用 127.0.0.1:5173 访问通常就能解决。
端口号段：5173 是怎么来的
端口号（Port Number）是操作系统用来区分同一台机器上不同网络服务的编号，范围是 0~65535。你可以把它理解成一栋楼的门牌号——IP 地址（localhost/127.0.0.1）是楼的地址，端口号是楼里的具体房间。5173 这个端口是 Vite 从 2.x 版本开始采用的默认值，它的选择不是随机的，背后有一段小故事——下一节会专门讲。
Vite 为何默认使用 5173 端口？
从 3000 到 5173：一次社区驱动的迁移
Vite 1.x 和早期 2.x 版本一度使用 3000 端口，与 Create React App、Express、Ruby on Rails 开发服务器共享同一个端口号。这在多项目开发场景下极其容易冲突——你在后台跑着一个 Express API，前台启动 Vite 时就会发现 3000 已被占用，Vite 自动递增到 3001，URL 一变又要手动更新代理配置。社区里关于这个问题的讨论在 GitHub 上累积了不少 issue，最终 Vite 团队在某次版本迭代时决定换掉这个"烫手山芋"。
选择 5173 这个数字的灵感据说来自开发团队的一位成员，他注意到手机九宫格键盘上 V、I、T、E 四个字母分别对应 5、1、7、3——凑在一起正好是 5173，既有品牌辨识度，又不是已经被广泛占用的热门端口。这种"彩蛋式命名"在开源社区里并不罕见，Node.js 的 REPL 默认端口 5000 也有类似的故事背景。
常见端口对比一览
| 端口 | 默认使用者 | 冲突风险 | 备注 |
|---|---|---|---|
| 3000 | Express / Rails / CRA / Next.js | 极高 | 最拥挤的开发端口 |
| 4000 | GraphQL Playground / Gatsby | 中等 | 全栈项目常用 |
| 5173 | Vite（默认） | 低 | VITE 键盘映射，当前最少冲突 |
| 8080 | Vue CLI / Java Tomcat / Nginx | 极高 | 后端开发者的"老习惯"端口 |
| 8000 | Django / Python HTTP Server | 中等 | Python 生态高频使用 |
以上数字均为公开技术规范，端口彩蛋来源于 Vite 社区讨论，仅供参考。
如何启动并访问 http //localhost 5173/？
从零开始跑起来一个 Vite 项目，整个过程不复杂，但每一步都有容易卡住的小坑。下面按真实操作顺序来走一遍，耗时约 5-10 分钟。
-
安装 Node.js（LTS 版本）
打开 nodejs.org 下载 LTS（长期支持）版本，目前建议 Node.js 20.x 或 22.x。安装完成后打开终端（Windows 用 PowerShell 或 CMD，Mac/Linux 用 Terminal），运行下面两条命令确认版本：
npm -v # 应输出 10.x.x 或更高
-
用官方脚手架创建 Vite 项目
在终端里选好你想放项目的目录，然后运行创建命令。
create vite@latest会拉取最新版 Vite 脚手架，my-app是你的项目目录名，可以自定义。
# 按提示选择：
# ✔ Select a framework: › Vue / React / Svelte / Vanilla
# ✔ Select a variant: › TypeScript / JavaScript
-
进入项目目录并安装依赖
脚手架创建完后，进入项目目录，运行 npm install 拉取 node_modules。第一次安装会根据网速不同耗时 30 秒到几分钟不等。建议用 npm 或 pnpm；不推荐用 cnpm，可能有依赖树解析差异。
-
启动开发服务器，打开 http //localhost 5173/
运行 npm run dev 后，终端里会出现类似下方的输出。把 Local 那行的地址完整复制到浏览器地址栏，页面跑起来就算成功。
➜ Local: http://localhost:5173/
➜ Network: use --host to expose
➜ press h + enter to show help
http://127.0.0.1:5173/ 而非 localhost，两者等价，直接打开即可。Vite 的 HMR（Hot Module Replacement，热模块替换）功能会在你保存文件后自动刷新浏览器里对应的模块，无需手动刷新整页。
整个流程走通之后，你的本机就成了一个小型的 Web 服务器，专门为这个前端项目提供文件服务。每次你修改源码，Vite 会在毫秒级内把变更推送到浏览器，这就是为什么 Vite 的开发体验比老一代工具快得多。
Vite 本地开发相关资源推荐榜
以下资源经本站编辑团队核实可用性，按实用度排序，格式与状态信息仅供参考，具体以官方源为准。
以上热度数据仅描述本站内容访问情况，不代表第三方平台真实数据。
localhost 5173 无法访问？系统排查手册
确认开发服务器真的在运行
这是最容易被忽略的一步。浏览器里报"无法访问此网站"，首先检查启动 Vite 的那个终端窗口有没有关掉，或者有没有出现报错（比如 package.json 找不到、依赖未安装等）。npm run dev 执行后终端必须停在 "ready" 的输出状态，不能退出。如果命令运行完就退出了，说明 Vite 启动失败，要先看报错信息。
检查端口是否被占用
5173 端口被其他进程占用时，Vite 默认会自动递增到 5174、5175……但也有些情况下会直接报错退出。用下面的系统命令查看端口占用情况：
# 找到 PID 后：tasklist | findstr {PID}
# 或直接：netstat -ano | findstr :5173 | findstr LISTENING
# 或：ss -tlnp | grep 5173
# 找到 PID 后 kill：kill -9 {PID}
如果确认端口被占用，可以 kill 掉对应进程，或者直接修改 Vite 的端口配置（见后文 vite.config 配置章节）。
防火墙与安全软件检查
在 Windows 系统上，第三方杀毒软件（如 360、火绒）有时会拦截本地回环端口的连接，尤其是非标端口（3000以下的端口一般在白名单里，5173 有时候不在）。临时关闭防火墙测试一下，如果页面能打开，说明是防火墙问题，需要在安全软件里给 Node.js 进程或 5173 端口放行。macOS 的防火墙默认不拦截本地回环，Linux 用户则需要检查 iptables 或 ufw 规则。
浏览器缓存与地址拼写问题
有时候浏览器的 Service Worker 缓存会导致页面显示旧内容甚至报错。打开开发者工具（F12），在 Network 面板勾选"禁用缓存"，或者直接用无痕模式访问。另外要注意地址栏里不要多加 https：Vite 默认是 http，如果浏览器自动跳转到 https://localhost:5173/ 就会连接失败。某些浏览器会因为你之前访问过 https 版本而强制跳转，可以在 Chrome 里打开 chrome://net-internals/#hsts，删除 localhost 的 HSTS 记录。
host: '0.0.0.0' 并通过 WSL2 的 IP（通常是 172.x.x.x）访问。
Node.js 版本不兼容
Vite 6.x 要求 Node.js 18 以上版本。如果你的系统里装了多个 Node.js 版本（比如用 nvm 管理），当前激活的版本可能太低。运行 node -v 确认版本，如果低于 18.x，用 nvm 切换到正确版本后重新运行 npm run dev。
自定义端口与 host：vite.config 配置详解
Vite 的核心配置文件是项目根目录下的 vite.config.js（或 vite.config.ts 如果用 TypeScript）。与 Webpack 的 webpack.config.js 类似，它控制着开发服务器的所有行为。
修改默认端口
在 server.port 字段里填入你想要的端口号。修改后，访问地址就从 http //localhost 5173/ 变成你指定的端口。
export default defineConfig({
server: {
port: 3000, // 改成你想要的端口
strictPort: true, // true=端口占用时报错退出，false=自动递增
}
})
strictPort 这个选项值得特别说一下：默认值是 false，表示端口被占用时 Vite 会自动递增端口号继续启动。设为 true 后，如果指定端口被占用，Vite 会直接报错退出——这在 CI/CD 流水线或者需要固定端口的场景下很有用，避免"悄悄换了端口但你不知道"的隐患。
将服务暴露到局域网
默认情况下，Vite 只监听 localhost（127.0.0.1），局域网里的其他设备（比如你用手机测试移动端适配）无法访问。设置 host: '0.0.0.0' 后，Vite 会监听所有网络接口，局域网内的设备就可以通过你电脑的局域网 IP（比如 192.168.1.100:5173）访问开发页面。
host: '0.0.0.0', // 或直接写 true，效果相同
port: 5173,
}
开启后，Vite 终端输出里会多出一行 Network 地址，直接把那个 IP:端口 地址发给手机或同事，他们就能在浏览器里预览你的页面。手机访问时要确保手机和电脑在同一个 Wi-Fi 网络下，且电脑防火墙允许 5173 端口的入站连接。
命令行临时指定端口
如果只是临时换一下端口，不想修改配置文件，可以直接在命令行里用 --port 参数：
# 或修改 package.json scripts：
# "dev": "vite --port 3001"
跨域问题处理：在 http //localhost 5173/ 环境中配置代理
跨域是怎么产生的
浏览器的同源策略（Same-Origin Policy）规定：只有协议、域名、端口三者完全相同的请求才算"同源"。你的前端页面运行在 localhost:5173，后端 API 运行在 localhost:8080（或者是远程服务器的某个域名），两者端口不同，就触发了跨域。浏览器会先发一个 OPTIONS 预检请求（Preflight Request），询问服务器"你允许我从 localhost:5173 发请求吗"；如果后端没有正确配置 CORS 响应头，浏览器就拒绝让前端 JS 读取响应。
在生产环境里，前端和后端通常部署在同一个域名下（或者后端配置了 CORS 白名单），所以这个问题不存在。但开发环境里，前端跑在 Vite 的 5173，后端跑在各自的端口，跨域几乎是必然的。Vite 的代理（proxy）功能是目前最优雅的解法：它让 Vite 开发服务器本身去请求后端，再把结果返回给浏览器——浏览器全程以为自己在和 localhost:5173 通信，不会触发跨域。
server.proxy 配置示例
port: 5173,
proxy: {
'/api': {
target: 'http://localhost:8080', // 真实后端地址
changeOrigin: true, // 修改请求头里的 Origin 为 target
rewrite: (path) => path.replace(/^\/api/, ''), // 去掉 /api 前缀
},
'/upload': {
target: 'https://api.example.com',
changeOrigin: true,
secure: false, // 目标是 https 但证书不受信时设为 false
},
}
}
配置完成后，前端代码里把 fetch('http://localhost:8080/users') 改成 fetch('/api/users')，Vite 收到 /api/users 请求后会自动转发到 localhost:8080/users，并把响应原封不动地返回给浏览器。
changeOrigin 为什么这么重要
changeOrigin: true 会让 Vite 在转发请求时，把 HTTP 请求头里的 Host 字段改成目标服务器的域名。有些后端框架（比如 Spring Boot 的某些安全配置、Nginx 的 server_name 校验）会校验 Host 头，如果发现 Host 是 localhost:5173 就拒绝请求。设置 changeOrigin 后，后端看到的 Host 就是自己的地址，不会有这个问题。
多项目并发运行与端口冲突管理
全栈项目或者微前端架构下，同时跑多个 Vite 项目是家常便饭。一个主应用、一个组件库预览、一个 mock 服务，三个终端窗口同时开着。如果不做端口规划，冲突是必然的。
固定端口策略：给每个项目分配专属端口
最简单的做法是在每个项目的 vite.config.js 里写死端口号，形成团队内约定。比如：主应用用 5173，组件库用 5174，后台管理用 5175，Mock 服务用 5176。这样所有人拉代码后直接 npm run dev，端口永远是固定的，不会产生混乱。把这个端口约定写进项目的 README.md 里，是个好习惯。
用 npm-run-all 一键启动所有项目
在 Monorepo（单仓多包）项目里，可以用 npm-run-all 或 concurrently 在根目录的 package.json 里配置一个 dev:all 命令，一键并行启动所有子项目：
Vite 自动端口递增机制
当你没有设置 strictPort: true 时，Vite 检测到 5173 被占用后会自动尝试 5174、5175……依次递增，直到找到空闲端口。这个机制在临时场景下很方便，但在团队协作里可能造成"你不知道自己的项目跑在哪个端口"的迷惑情况。建议多人协作项目里，关键项目都设置 strictPort: true 并固定端口，确保每个人的环境一致。
从 http //localhost 5173/ 到生产部署：环境变量与构建差异
环境变量文件的加载规则
Vite 通过项目根目录下的 .env 系列文件管理环境变量。加载优先级从高到低是：.env.local、.env.development.local、.env.development、.env。运行 npm run dev 时读取 development 系列，运行 npm run build 时读取 production 系列。
VITE_APP_TITLE=我的应用（开发版）
# 只有 VITE_ 开头的变量才会暴露给客户端代码
VITE_APP_TITLE=我的应用
在代码里读取环境变量
Vite 把环境变量挂在 import.meta.env 对象上，而不是 Node.js 的 process.env。这是 Vite 与 Webpack/CRA 的一个重要区别，初学者经常在这里踩坑。
// 开发时：http://localhost:8080/api
// 生产时：https://api.myapp.com/api
if (import.meta.env.DEV) {
console.log('当前是开发模式')
}
VITE_ 开头的变量会被打包进客户端代码，在浏览器里可以被任何人读取。数据库密码、API 密钥等敏感信息绝对不能放进 VITE_ 变量，应放在服务端环境变量里。
构建产物与开发服务器的本质区别
运行 http //localhost 5173/ 时，Vite 以"按需编译"模式工作：浏览器请求哪个模块，Vite 就即时编译哪个，不做整体打包。这让启动速度极快，但产物是未压缩的 ESM 模块。运行 npm run build 后，Vite 切换到 Rollup 引擎做完整打包：Tree-shaking（摇树优化，去掉未使用的代码）、代码分割（Code Splitting）、资源压缩全部上阵，产出的 dist 目录才是真正能部署到服务器的生产文件。
关于 http //localhost 5173/，全网都在搜什么？
以下数据来自搜索引擎（Bing 站长工具）针对 http //localhost 5173/ 相关词的近 30 天真实搜索印象量，按意图分组整理，帮你一眼看清用户真实需求分布。
数据来源：搜索引擎相关搜索词，近 30 天印象量，数字为近似值，仅供参考，不代表精确用户量。
FAQ：关于 http //localhost 5173/ 的高频疑问
http //localhost 5173/ 无法访问，浏览器报"ERR_CONNECTION_REFUSED"怎么办？
ERR_CONNECTION_REFUSED 的字面意思是"连接被拒绝"，通常意味着目标端口上根本没有服务在监听，而不是防火墙拦截（防火墙拦截一般是 ERR_CONNECTION_TIMED_OUT）。排查步骤：
第一步，确认终端里 Vite 的进程还在运行，没有崩溃退出。第二步，检查 Vite 实际监听的端口——如果 5173 被占用，Vite 可能自动切到了 5174，终端输出里会有提示。第三步，确认浏览器地址栏里是 http 而非 https，两者端口相同但协议不同，连接目标完全不一样。第四步，如果以上都没问题，尝试直接访问 http://127.0.0.1:5173/ 替代 localhost，排除 DNS 解析问题。
Vite 为什么默认用 5173 而不是 3000 端口？
3000 端口是前端生态里冲突最严重的端口，Express、Create React App、Next.js、Rails 都默认用它。Vite 团队在 2.x 版本时把默认端口换成了 5173——这个数字来自 VITE 四个字母在九宫格键盘上的映射（V=5, I=1, T=7, E=3），既有品牌辨识度，又是一个相对冷门、不容易被其他工具占用的端口。
如果你的项目里有历史原因必须用 3000，在 vite.config.js 里设置 server.port: 3000 即可，Vite 完全支持自定义端口。
手机怎么访问电脑上运行的 http //localhost 5173/？
localhost 只能在本机访问，手机要访问需要两步：第一，在 vite.config.js 里设置 server.host: '0.0.0.0'（或 true），让 Vite 监听所有网络接口；第二，手机和电脑连同一个 Wi-Fi，用电脑的局域网 IP（Windows 运行 ipconfig，Mac 运行 ifconfig 查看，通常是 192.168.x.x）加端口号访问，例如 http://192.168.1.100:5173/。
如果还是访问不了，检查电脑防火墙是否允许 5173 端口的入站连接。Windows 可在"高级安全 Windows Defender 防火墙"里新建入站规则放行该端口。
开发时在 http //localhost 5173/ 调接口报跨域，生产环境会有同样问题吗？
不一定，要看生产环境的部署方式。如果前端静态文件和后端 API 部署在同一个域名下（比如都在 api.myapp.com，前端走根路径、后端走 /api 路径），生产环境就不存在跨域问题。如果前后端分离部署在不同域名，生产环境同样需要处理跨域——通常由后端在响应头里加 Access-Control-Allow-Origin，或者用 Nginx 做反向代理把两者合并到一个域名下。
开发时用 Vite 的 server.proxy 解决跨域，只是开发阶段的临时方案，不影响生产构建。上线前务必确认生产环境的跨域策略已经配置好。
npm run dev 和 npm run build 有什么本质区别？
npm run dev 启动的是 Vite 开发服务器，代码按需编译、不做压缩、支持 HMR 热更新，访问地址就是 http //localhost 5173/。这个模式下的代码是未优化的，体积大、包含调试信息，只适合开发调试用。
npm run build 调用 Rollup 做完整打包，输出到 dist 目录：所有代码经过 Tree-shaking、压缩混淆、代码分割，图片等资源也会被处理。dist 目录里的文件才是真正要部署到服务器的产物。构建完成后可以用 npm run preview 在本地预览生产版本，它会在另一个端口（默认 4173）启动一个静态文件服务器。
本站内容的准确性和时效性如何保证？
本站内容以 Vite 官方文档、Node.js 官方文档及社区公开讨论为主要依据，编辑团队定期核对关键配置项与版本变更。对于尚未在官方文档中明确说明的细节，我们会标注"据社区讨论"或"实测结论"，不做无依据的臆断。
Vite 版本迭代较快，部分 API 在不同版本间有差异。本页以 Vite 6.x 为基准，如果你使用的是更早版本，建议对照官方 CHANGELOG 确认配置项是否适用。如发现内容有误或过时，欢迎通过页脚联系方式反馈。
内容由谁来写
以上为用于说明内容分工的角色介绍，具体履历与机构归属以官方公开资料为准。
本站内容覆盖能力
以上数字仅用于描述本站内容规模与更新情况，不代表真实用户量、访问量或第三方背书。
读者评论
跟着这个配置终于把 Vite 跑起来了！之前折腾了一下午防火墙的问题，这里的排查步骤太准了，netstat 那条命令直接定位到了占用 5173 的进程。
5173 端口名字来源那段没想到，原来是键盘映射，涨知识了哈哈
代理配置那段能再加个 changeOrigin 的详细说明吗？我们后端 nginx 会校验 Host 头，不加这个死活转发不过去，坑了好久。哦等等，文章里已经讲了，我没看完😅
第一次学 Vue，看到终端里出现 localhost:5173 完全不知道是什么意思，这篇从头到尾解释得很清楚，连 http 和 https 的区别都讲了，适合我这种新手！
React 项目也完全适用，不只是 Vue，赞一个。多项目并发那块我现在用 5173、5174、5175 三个窗口同时跑，完全没问题。
环境变量那块对我帮助最大。之前总是把 .env.development 里的接口地址带到生产环境，上线就挂，看完这篇终于搞清楚 VITE_ 前缀的规则了。
strictPort: true 这个选项之前不知道，以前总是 Vite 悄悄换了端口但代理配置还指向旧端口，排查半天。现在设成 true 直接报错，反而更好定位。
请问 host: '0.0.0.0' 配置后手机还是访问不了怎么办？我电脑和手机在同一个 Wi-Fi 下的。
以上评论为用于展示内容互动的示例，不代表真实用户数据。