*.localhost 本地域名与前端开发最小配置模板

归类：前端 / 本地开发 状态：✅ 已验证

一、结论先行

*.localhost 一般可以直接作为本机开发域名使用，不需要手动修改 /etc/hosts。

常见可用形式：

• http://localhost:3000
• http://test-host.localhost:3210
• http://openclaw-control.localhost:3191

这不是某个框架的特性，而是现代浏览器和系统通常会把 *.localhost 解析到本机回环地址。

二、为什么以前经常要改 hosts

以前常见的本地域名是：

• demo.test
• myapp.local
• foo.dev

这类域名默认不会自动指向本机，因此通常要手动改 /etc/hosts。

而 *.localhost 属于更适合本地开发的特殊保留域名，现代环境下通常不需要再额外做 hosts 映射。

三、要想正常访问，还需要满足什么条件

即使 *.localhost 能解析到本机，前端项目还是要满足下面几个条件：

1. 本地开发服务真的在监听对应端口。
2. 开发服务器允许这个 Host 访问，而不是只接受 localhost。
3. 如果使用 HMR，WebSocket 或 SockJS 的公开地址也要和自定义域名一致。

如果这几项没配好，常见表现是：

• 页面打不开
• Invalid Host header
• 首屏能开，但热更新连接失败

四、Vue CLI 最小可用模板

适合 @vue/cli-service 老项目。

// vue.config.js
const devHost = process.env.DEV_HOST || 'my-app.localhost'
const devPort = Number(process.env.PORT || 3210)

module.exports = {
  devServer: {
    host: '127.0.0.1',
    port: devPort,
    public: `${devHost}:${devPort}`,
    disableHostCheck: true,
    open: false
  }
}

{
  "scripts": {
    "serve:localhost": "cross-env DEV_HOST=my-app.localhost PORT=3210 vue-cli-service serve"
  }
}

访问方式：

http://my-app.localhost:3210

实测补充

在一个 Vue 2 + TypeScript 的真实项目 test-host 中，上述配置已验证可用：

• 启动命令：npm start
• 访问地址：http://test-host.localhost:3210
• 返回结果：HTTP 200

如果老项目安装依赖时触发 peer dependency 冲突，可尝试：

npm install --legacy-peer-deps

五、Vite 最小可用模板

// vite.config.ts
import { defineConfig } from 'vite'

const devHost = process.env.DEV_HOST || 'my-app.localhost'
const devPort = Number(process.env.PORT || 5173)

export default defineConfig({
  server: {
    host: '127.0.0.1',
    port: devPort,
    strictPort: true,
    hmr: {
      host: devHost,
      port: devPort
    }
  }
})

{
  "scripts": {
    "dev:localhost": "cross-env DEV_HOST=my-app.localhost PORT=5173 vite"
  }
}

六、webpack-dev-server 最小可用模板

适合没有 Vue CLI 包装的原生 webpack 项目。

// webpack.config.js
const devHost = process.env.DEV_HOST || 'my-app.localhost'
const devPort = Number(process.env.PORT || 8080)

module.exports = {
  devServer: {
    host: '127.0.0.1',
    port: devPort,
    allowedHosts: 'all',
    client: {
      webSocketURL: `ws://${devHost}:${devPort}/ws`
    }
  }
}

七、什么时候仍然可能需要额外配置

下面这些场景里，*.localhost 之外还可能需要更多设置：

• 你的 dev server 默认启用了严格的 Host 校验
• 你使用 HTTPS 本地证书
• 你通过容器、远程开发机或反向代理访问本地服务
• 你所在的工具链版本较老，对自定义本地域名支持不完整

这时优先检查的通常不是 DNS，而是：

1. allowedHosts 或 disableHostCheck
2. HMR / WebSocket 的公开地址
3. 绑定的监听地址和端口

八、推荐做法

如果只是本机多项目开发，优先使用 *.localhost 而不是手工维护 hosts：

• 成本更低
• 命名更清晰
• 便于隔离 Cookie、LocalStorage 和本地面板入口

推荐命名方式：

• control-center.localhost
• help-center.localhost
• test-host.localhost
• demo-admin.localhost