Vite在Laravel中HMR启动失败时，须先排查5173端口是否被占用或被Windows系统保留（5172–5271），再通过vite.config.js设server.port=3000、strictPort:true确保端口显式生效，避免@vite指令请求错误地址导致404。
当你在 Laravel 项目中运行 vite 开发服务器时，HMR（热模块替换）默认监听 http://localhost:5173，但该端口常被其他进程、系统保留或前次未退出的 dev server 占用，导致启动失败或页面白屏、资源 404、@vite 指令不加载 JS —— 此时必须显式指定新端口并确保配置生效路径完整。
确认端口是否真被占用
先打开终端，执行：netstat -aon | findstr :5173（Windows）或 lsof -i :5173（macOS/Linux）。若输出含 PID，则说明有进程正在使用；若无输出，但启动仍失败，很可能是 Windows 系统保留端口范围（5172–5271）导致拒绝绑定 —— 这种情况不能靠杀进程解决，必须改端口。
这一步跳过会导致后续所有配置白忙：你改了 vite.config.js，却仍卡在“Address already in use”或静默失败。
方法一：修改 vite.config.js（推荐，持久生效）
打开项目根目录下的 vite.config.js，在 defineConfig({}) 对象内添加 server 配置块：
找到 plugins: [laravelVitePlugin({...})] 所在层级，在其同级位置插入：
server: { port: 3000, host: '0.0.0.0', strictPort: true }
【strictPort: true 是关键】 它让 Vite 在端口不可用时直接报错退出，而不是自动降级到 5174——避免你以为改了端口却实际跑在未预期的地址上，导致 @vite 指令仍尝试请求 localhost:5173 而 404。
保存后重启服务：npm run dev。此时终端应明确显示 “Local: http://localhost:3000/”，且浏览器打开该地址能正常加载页面和 HMR。
方法二：通过 .env 文件统一管理（跨环境一致）
在项目根目录（与 package.json 同级）新建文件，命名为 .env（注意：无任何后缀），写入：
VITE_PORT=3000VITE_OPEN=true
⚠️ 文件名必须是 .env，不是 .env.local 或 .env.development；变量名必须以 VITE_ 开头，否则 Vite 不读取。
然后修改 vite.config.js，将 port 值改为动态读取：
port: Number(process.env.VITE_PORT) || 5173
这样既能复用环境变量，又保留 fallback。改完后必须重启开发服务器，否则新端口不会生效。
方法三：命令行临时覆盖（仅本次生效）
直接在终端运行：npx vite --port 3000
或者修改 package.json 中的 "dev" 脚本为："dev": "vite --port 3000"
这个方式适合快速验证端口可用性，但不建议长期使用——它绕过了 Laravel Vite 插件对 host 和 https 的协同配置，可能导致 @vite 注入的开发代理地址错误，例如生成 http://localhost:3000/@vite/client 但实际服务监听的是 0.0.0.0:3000，造成跨域或连接拒绝。
验证 HMR 是否真正生效
第一步：打开浏览器开发者工具 → Network 标签页，刷新页面，确认所有 JS/CSS 请求域名是 localhost:3000，而非 localhost:5173。
第二步：修改任意一个 Vue 组件的模板文字，保存；观察浏览器是否自动刷新或局部更新，且控制台无 WebSocket 连接错误。
第三步：检查 Blade 模板中 @vite(['resources/js/app.js']) 渲染出的 script 标签 href 属性，应为 http://localhost:3000/@vite/client 和 http://localhost:3000/resources/js/app.js —— 若仍是 5173，说明 vite.config.js 中的 server.host 未设为 '0.0.0.0' 或 true，Laravel 插件无法正确识别开发服务器地址。
第四步：在手机浏览器访问 http://[你的局域网IP]:3000（如 http://192.168.1.100:3000），确认能加载页面且 HMR 正常工作 —— 这要求 host: '0.0.0.0' 已启用，且本地防火墙放行该端口。
