做开发这些年我改过的 hosts 文件次数大概比提交的 commit 还多。新项目拉下来第一步往往就是在开发环境配置里把本地 hosts 改掉让api.myapp.test指向127.0.0.1而不是让代码里到处散落着127.0.0.1:8080。很多刚入行的同学第一次听到这件事会愣一下动一个系统文件就能把我编出来的域名指到本机答案是真能而且这是成本最低、依赖最少、离线也能跑的做法。这篇东西写给三类人看。第一类是刚入行、被本机地址和线上域名来回切换折腾到头晕的后端同学你大概率正在为回调地址、Cookie 域、静态资源跨域发愁。第二类是需要联调第三方登录、单点登录、本地 HTTPS 的前端同学域名的细微差别会直接决定你能不能调试成功。第三类是要带新人、想把本地开发环境做成一套可复制模板的团队负责人。我会从 hosts 的解析原理讲到三大系统的操作细节再讲到端口处理、泛域名、容器环境、常见故障排查每个环节都给出可以直接抄走的配置和脚本。全文不涉及任何外部网络的特殊玩法纯粹是本机开发环境的搭建经验。1. 本地 hosts 改动背后的真实需求拆解1.1 hosts 文件的本质一张系统级的通讯录操作系统在真正去问 DNS 服务器这个域名对应哪个 IP之前会先翻一张本地的静态表这张表就是 hosts 文件。它的结构极其简单一行一条记录格式是IP地址 主机名 [别名1 别名2 ...]中间用空格或者 Tab 分隔#开头的是注释。比如127.0.0.1 api.myapp.test这行的意思就是凡是本机要解析api.myapp.test这个名字答案就是127.0.0.1不用再往外问了。关键在于优先级这三个字。Linux 和 macOS 上解析顺序由/etc/nsswitch.conf里那一行hosts: files dns决定files排在前面就意味着先读 hosts 文件读到了就直接返回读不到才去dns那一层。Windows 的顺序是写死的同样是 hosts 优先、DNS 兜底。所以你在 hosts 里写的记录等于给本机装了一个最高优先级的解析答案任何程序走标准解析流程都会拿到它。这一点带来两个直接好处。一是离线可用你在地铁上、在客户现场没有网络照样能把整套开发环境跑起来。二是可控解析结果完全由你说了算不受运营商 DNS 缓存、不受公司内网 DNS 策略影响。很多人只知道 hosts 能屏蔽广告其实它在开发环境里的价值远大于此它是整个本地环境的地基。1.2 为什么不该直接拿 127.0.0.1 硬编码开干我最开始写项目的时候也觉得改 hosts 是多余动作代码里写死http://localhost:8080不也能跑吗直到踩了几次坑才明白这么做会在四个地方给你埋雷。第一个雷是回调地址。第三方开放平台、支付网关、单点登录服务几乎都会校验回调地址的域名白名单而且很多平台明确不接受 IP 形式的回调地址。你在本机用127.0.0.1:3000/callback去调试配置页面根本存不进去测试账号也申请不下来。换成http://app.myapp.test/callback问题当场消失因为它长得就像一个正常域名。第二个雷是 Cookie 作用域。浏览器的 Cookie 是按域绑定的localhost是一个没有顶级域的孤岛你在localhost上设的 Cookie子域之间没法共享Domain.myapp.test这种写法在 localhost 上完全失效。想把登录态存主域、子系统读主域这套逻辑在本地跑通就必须有真实域名。第三个雷是跨域策略。前后端分离的项目前端跑在 5173、后端跑在 8080如果两边都用127.0.0.1只是端口不同浏览器判定为同源你反而测不出真实的跨域场景。等到上线才发现 CORS 配置有问题那就晚了。第四个雷是环境变量污染。代码里散落着几十处硬编码地址某天要把测试环境切到预发环境你得全局搜索替换一遍漏一处就出事。统一用域名之后改配置只需要动一个地方。1.3 什么时候其实不该改 hosts也不是所有场景都值得动 hosts。如果你的项目就是一个纯前端静态页面没有任何后端交互也不涉及登录态和回调那直接用localhost:5173是最快的方式多此一举。还有一种情况是团队里有人图省事把所有线上域名在 hosts 里指到本机结果某天排查线上问题时忘了自己改过本地复现出来的现象和真实线上对不上白白浪费半天。我的习惯是给托管片段加明显的注释头尾标记并且只写.test这类本地专用后缀绝不把线上域名往 hosts 里写。再有就是移动端真机调试。手机系统的 hosts 文件没有 root 权限改不了硬凑也没意义。这种场景更适合在路由器上配一条本地 DNS 记录或者老老实实在手机上装一个能指定测试环境的包。方向选错了后面所有努力都是白费。2. 三个系统下的 hosts 文件操作细节2.1 Windows权限、编码与扩展名三个坑Windows 的 hosts 路径是C:\Windows\System32\drivers\etc\hosts这个文件从 Vista 开始就受系统保护普通权限打开是只读的。最稳的打开方式是以管理员身份启动编辑器比如在开始菜单搜到 VS Code 或者 Notepad右键以管理员身份运行然后在编辑器里打开这个路径。用命令行的话管理员权限的 CMD 里执行notepad C:\Windows\System32\drivers\etc\hosts也可以重点是一定要管理员。第一个坑是扩展名。如果你新建一个文本文件改完再拖进这个目录很容易被存成hosts.txt而系统只认没有扩展名的hosts。用记事本另存为的时候文件名那一栏要加英文双引号包起来写成hosts才能避免被自动补上.txt。第二个坑是编码。老版本记事本默认存成带 BOM 的 UTF-8部分情况下会导致解析异常表现为某几条记录莫名其妙不生效。现在 Win10 以后的记事本默认是无 BOM 的 UTF-8问题少了很多但如果你用一些老旧编辑器记得手动选 UTF-8 无 BOM 或者纯 ASCII。只写英文域名和 IP 的话其实 ANSI 最省事。第三个坑是安全软件。一些终端防护类软件会把 hosts 文件锁定你保存的瞬间不报错重启之后记录全没了或者直接被还原成系统默认内容。判断方法是看文件属性里只读有没有被勾上以及保存后用文本编辑器再打开确认一眼。如果每次都被还原就得去安全软件里把这个文件的保护关掉。改完之后立刻验证ping api.myapp.test看返回的 IP 是不是你写的那一个。记住nslookup不会读 hosts 文件它直接去问 DNS用它验证会得到解析失败的假象别被误导。2.2 macOS 与 Linuxsudo、nsswitch 与解析顺序macOS 和 Linux 的路径都是/etc/hosts改的时候需要提权sudo vim /etc/hosts是最常见的姿势。文件格式和 Windows 完全一样也是IP 域名一行一条。写 IPv6 的话用::1 api.myapp.test。Linux 上值得多看一眼的是/etc/nsswitch.conf。这个文件里有一行大概长这样hosts: files dns myhostname。files排在dns前面hosts 文件才有优先权。有些容器镜像或者精简系统会把它改成hosts: dns files这时候你在 hosts 里写的记录会被 DNS 结果覆盖表现为改了完全没用。遇到反常情况先cat /etc/nsswitch.conf | grep hosts确认一眼。验证命令上Linux 和 macOS 推荐用getent hosts api.myapp.test它走的是完整的系统解析链路会读 hosts结果最可信。macOS 上还可以用dscacheutil -q host -a name api.myapp.test来查缓存里的解析结果。dig和nslookup同样是绕过 hosts 的只用来排查 DNS 侧的问题别用来验证 hosts。另外提一句域名解析是不区分大小写的你写API.MyApp.Test和api.myapp.test效果一样没必要纠结。但主机名后面千万不要手抖多打空格、多打中文标点这些细节会直接导致那一行被解析器忽略而且不报错非常难查。2.3 改完必须执行的缓存刷新命令改完 hosts 只是第一步操作系统和浏览器各自都缓存了 DNS 结果不刷新的话你看到的现象可能和实际配置不一致。三个平台的刷新命令我整理成了一张表建议直接存进笔记。系统刷新命令备注Windowsipconfig /flushdns需要普通权限即可macOS 10.10sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder两条一起执行Linux (systemd-resolved)sudo resolvectl flush-caches老版本用systemd-resolve --flush-cachesLinux (nscd)sudo systemctl restart nscd装了 nscd 才需要浏览器 (Chromium 系)打开chrome://net-internals/#dns点 Clear host cache顺手清一下 socket 池刷新完别急着开页面先ping一下确认解析再动浏览器。这套顺序能帮你把到底是解析问题还是服务问题当场分开少绕很多弯路。还有个容易被忽略的点Windows 上如果开了 Hyper-V 或者装了 Docker Desktop会有虚拟网卡参与网络栈极个别情况下 hosts 的改动要等几秒才生效。如果你刚改完就测等五秒再试一次不要立刻下结论。3. 域名选型与端口处理hosts 搞不定的那部分3.1 用什么后缀做本地域名更安全本地域名不是随便编的用错了后缀会带来一堆莫名其妙的麻烦。RFC 6761 明确保留了几个永远不会被注册的顶级域.test、.example、.invalid、.localhost。其中.test是社区里做本地开发最通用的选择我强烈推荐统一用它。为什么不用.local这个后缀在 RFC 6762 里被分配给 mDNS也就是苹果的 BonjourmacOS 和部分 Linux 发行版会用组播去解析.local结尾的名字。你在 hosts 里写一条127.0.0.1 printer.local有时候会被 mDNS 抢先响应表现就是解析结果时好时坏非常折磨人。为什么不用.dev这是新手最容易踩的坑。整个.dev顶级域都在浏览器的 HSTS 预加载列表里意味着浏览器对你的.dev域名强制走 HTTPS你写http://app.dev会被浏览器内部升级成https://app.dev如果本地没有配置证书直接报连接错误。你要么老老实实配本地 HTTPS 证书要么干脆换后缀。.com、.cn这类真实后缀更别碰一是理论上有和真实站点撞车的可能二是很多企业内网会自动跳转到公司门户排查起来费时费力。结论很简单本地开发统一用.test这是最省心的答案。3.2 hosts 不能带端口那端口怎么办这是被问得最多的一个问题hosts 文件配置域名可以加端口吗答案是明确不行。hosts 文件工作在域名解析层它只负责把名字翻译成IP 地址压根不知道端口这回事。你写127.0.0.1:8080 api.myapp.test整个文件都会解析异常。所以带端口的写法只能是http://api.myapp.test:8080端口还得写在 URL 里。如果端口是 80 或者 443浏览器允许省略写http://api.myapp.test就等于 80 端口。这就引出了一个非常实用的思路把本地服务的监听端口挪到 80 和 443 上域名后面就不用带端口了。但在 Windows 上80 端口经常已经被系统组件或者某些后台服务占用服务起不来还报一个权限不足或者地址已被占用。先排查占用情况netstat -ano | findstr :80拿到最后一列的 PID再去任务管理器里看是哪个进程。确认能腾出来之后再让服务监听 80。如果 80 端口腾不出来还有一个更优雅的方案见下一节。3.3 用 Nginx 做统一入口把端口藏起来我现在的标准做法是所有本地服务都跑在高位端口3000、8080、9000 之类前面挂一个 Nginx 监听 80 和 443按域名转发到对应的后端。这样你访问http://api.myapp.test就是干净的带不带端口这件事从此不用再想。# 按域名分发一个入口管所有本地服务 server { listen 80; server_name api.myapp.test; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } } server { listen 80; server_name web.myapp.test; location / { proxy_pass http://127.0.0.1:5173; proxy_set_header Host $host; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; } }这里有几个细节必须说清楚。proxy_set_header Host $host这行千万别省它的作用是把浏览器请求里的原始域名透传给后端。少了这一行后端拿到的是127.0.0.1:8080如果它要用这个值拼回调地址、拼跳转链接生成出来的 URL 就是错的你会看到页面莫名其妙跳到了本机地址。第二段配置里的Upgrade和Connection两行是给前端热更新用的Vite 和 webpack 的 HMR 都走 WebSocket不配这两行热更新会一直重连失败控制台里刷一片报错。这是很多人配完 Nginx 之后页面能打开但热更新失效的根因。还有个细节是X-Forwarded-Proto。本地走的是 http但某些后端框架会根据这个头判断请求协议用来决定 Cookie 要不要加 Secure 标记。老老实实传上去能省掉一类本地登录成功但刷新就掉线的怪问题。4. 从能解析到能调试前端与后端的联调配置4.1 Vite 与 webpack devServer 的 allowedHosts 坑改完 hosts 之后打开浏览器很多人会遇到这样一条报错Blocked request. This host (web.myapp.test) is not allowed.这不是 hosts 的问题而是 Vite 4.0 之后新增的安全检查。开发服务器默认只接受localhost和 IP 形式的 Host 头你用了自定义域名就会被拦下来。解决办法是在vite.config.js里显式放行import { defineConfig } from vite export default defineConfig({ server: { host: 0.0.0.0, port: 5173, strictPort: true, allowedHosts: [.myapp.test, localhost] } })allowedHosts传入以点开头的后缀可以一次性放行整个子域比逐个列域名省事。webpack 侧的对应配置是devServer.allowedHosts旧版本用的是disableHostCheck: true写法上略有区别但道理一样告诉开发服务器这个域名是我自己人。host: 0.0.0.0也值得单独说一句。默认情况下 Vite 只监听回环地址本机访问没问题但如果你要用手机连同一个 Wi-Fi 做真机预览或者用 Docker 跑开发服务就必须放开到0.0.0.0否则外部怎么都连不上。放开之后记得别在公共网络环境下开这个服务同一网段的人能直接访问到你的代码。4.2 本地 HTTPS 与受信证书有一类功能在 http 下根本测不了。比如浏览器的地理定位、摄像头调用、Service Worker 注册、部分 OAuth 平台的回调都要求页面运行在安全上下文里。本地要凑齐 HTTPS就要有一张浏览器认的证书。以前的做法是自己用 openssl 生成自签证书然后每次都被浏览器拦下来点继续访问而且接口请求经常因为证书不受信直接失败。现在我的标准工具是 mkcert它会在本机装一个根证书到系统信任区再用这个根证书签发你的本地域名证书浏览器打开就是绿锁没有任何警告。# 安装后先初始化根证书 mkcert -install # 一条命令生成覆盖你需要的所有名字的证书 mkcert -cert-file ./certs/myapp.pem \ -key-file ./certs/myapp-key.pem \ myapp.test *.myapp.test localhost 127.0.0.1 ::1注意*.myapp.test必须加引号否则 shell 会尝试做通配符展开把那几个字符解释成当前目录下的文件名生成出来的证书就缺了泛域名。证书生成好之后把cert和key两个路径配到 Nginx 的ssl_certificate和ssl_certificate_key上或者配到 Vite 的server.https里都行。这里有个团队协作的坑mkcert 生成的根证书是每台机器独立的没法共享给同事用。所以别把证书文件提交到仓库里让大家共用正确做法是在项目 README 里写清楚执行mkcert -install和下面这条命令让每个人在自己机器上生成一份。证书文件本身要加进.gitignore。4.3 Cookie 域、SameSite 与跨子域登录态把主域和各个子域都写进 hosts全部指向127.0.0.1这是本地调多系统登录的标准姿势127.0.0.1 myapp.test 127.0.0.1 auth.myapp.test 127.0.0.1 app.myapp.test 127.0.0.1 admin.myapp.test这样做的直接收益是 Cookie 可以设为Domain.myapp.test浏览器会把它带到所有子域上单点登录在本地就能跑通。如果全是localhost这套逻辑根本没法验证。但 Cookie 还有两个属性经常在本地翻车。一个是Secure加了它浏览器只允许在 HTTPS 下存储和发送。本地跑 http 时Set-Cookie里带Secure的响应会被浏览器直接丢弃表现就是登录接口返回 200 但 Cookie 没存下来。要么本地配上 HTTPS要么在开发环境把Secure关掉——我倾向于用配置区分别在代码里硬编码。另一个是SameSite。SameSiteNone必须和Secure配对使用在 http 下不生效。如果你的系统需要跨站带 Cookie本地测试就绕不开 HTTPS 这条路。这就是为什么前面花那么大篇幅讲 mkcert它不是一个可选项而是某些功能调试的必经之路。5. 泛域名、多域名与团队协作的工程化做法5.1 dnsmasq 实现泛解析摆脱逐条维护项目稍微大一点域名数量就压不住了api.test、api-v2.test、user-api.test、order-api.test……每加一个微服务就要在 hosts 里加一行还得通知所有同事跟着加非常低效。*.myapp.test这种通配写法在 hosts 文件里是不支持的解析器会把星号当普通字符处理写了也没用。解决办法是引入一个本地 DNS 服务让它在域名匹配不上时返回一个固定地址。dnsmasq 是最常用的那个配置一行就够# /usr/local/etc/dnsmasq.conf address/.myapp.test/127.0.0.1然后在系统 DNS 设置里把127.0.0.1加为第一顺位的解析服务器这样所有以.myapp.test结尾的域名都会拿到127.0.0.1再也不用管具体子域叫什么。macOS 上还有一个更轻的写法不需要装任何服务。只要新建/etc/resolver/test文件内容是nameserver 127.0.0.1系统就会把.test后缀的查询全部交给本机的 DNS 服务。当然前提是你本机确实跑着一个 DNS 服务。Windows 没有这类内置机制比较现实的做法是项目初始化脚本自动往 hosts 里追加需要的记录或者干脆装个支持泛解析的本地 DNS 服务。别硬扛工具解决的问题就用工具解决。5.2 用 hosts 管理工具做方案切换与模板手改/etc/hosts最大的问题是没法版本化、没法快速切换。今天调 A 项目明天调 B 项目来回注释和取消注释特别容易出错。SwitchHosts 这类工具能明显改善体验。它让你把不同项目的 hosts 内容存成独立的方案随时勾选启用或关闭还支持从远程 URL 拉取配置。我一般的做法是在项目仓库里放一个docs/hosts.example文件内容就是当前项目需要的全部记录新人 clone 下来复制到工具里勾上就完事。这个hosts.example文件要遵守两个约定。一是带上说明注释写清楚每条记录对应哪个服务、跑在哪个端口。二是只放.test后缀的域名不掺任何线上地址避免有人误启用之后把真实流量引到本机。下面是我常用的模板结构# myapp 本地开发 hosts # api - 后端主服务 (8080) # web - 前端开发服务器 (5173) # admin - 后台管理系统 (8081) 127.0.0.1 myapp.test 127.0.0.1 api.myapp.test 127.0.0.1 web.myapp.test 127.0.0.1 admin.myapp.test5.3 Docker 容器与 WSL 里的 hosts 是另一份这一步坑了很多人你把宿主机的 hosts 改好了浏览器访问正常但跑在容器里的服务访问同一个域名却解析失败。原因很简单容器有自己独立的网络命名空间/etc/hosts是容器镜像里那一份跟宿主机的完全没关系。Docker Compose 里可以用extra_hosts补上services: api: image: myapp/api:dev extra_hosts: - db.myapp.test:host.docker.internal - redis.myapp.test:host.docker.internalhost.docker.internal是 Docker Desktop 提供的特殊主机名指向宿主机。在 Linux 上如果这个特殊域名不可用可以显式指定宿主机的网桥地址或者在docker run时加--add-hostdb.myapp.test:172.17.0.1。WSL2 又是另一套逻辑。WSL 里的/etc/hosts是系统启动时自动生成的你手动改的内容在wsl --shutdown之后会被覆盖。想让它保留下来需要关掉自动生成# /etc/wsl.conf [network] generateHosts false generateResolvConf false关掉generateResolvConf之后要自己维护/etc/resolv.conf写一个能用的 DNS 地址进去否则整个 WSL 会断网。这两项改完执行wsl --shutdown重启生效之后再改 hosts 就不会被冲掉了。5.4 一个带标记位的一键切换脚本既然要频繁改就写个脚本用注释标记圈出托管区域脚本只负责替换这两行标记之间的内容不会碰你自己加的其他记录。#!/usr/bin/env bash set -euo pipefail HOSTS_FILE/etc/hosts TEMPLATE./hosts.dev.txt BEGIN# devkit begin END# devkit end tmp_file$(mktemp) trap rm -f $tmp_file EXIT # 删掉旧的托管段落保留其他所有内容 awk -v b$BEGIN -v e$END $0 b { skip 1; next } $0 e { skip 0; next } !skip { print } $HOSTS_FILE $tmp_file # 追加新的托管段落 { echo $BEGIN cat $TEMPLATE echo $END } $tmp_file sudo cp $tmp_file $HOSTS_FILE # 按平台刷新缓存 case $(uname -s) in Darwin) sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder ;; Linux) sudo resolvectl flush-caches 2/dev/null || true ;; esac echo hosts 已更新这个脚本的价值在于幂等。反复执行不会重复追加记录也不会把你手动加的临时条目删掉因为 awk 只过滤标记之间的内容。trap那行保证脚本中途出错时临时文件会被清理不会在/tmp里堆一堆垃圾。团队里跑起来比挨个口头交代记得加这条靠谱得多。6. 四类典型场景的落地配置6.1 第三方登录回调的本地调试做第三方登录联调时平台后台一般要求你填回调域名很多平台不接受 IP也不接受带端口的形式。本地调试的思路是把回调地址填成http://app.myapp.test/callback同时在 hosts 里把这几个域名指向本机再在本地服务里拦截这个路径处理授权码。有一个细节要注意部分平台会校验回调域名的主域名是否在备案白名单内这种情况下你没法拿一个假域名糊弄过去只能走平台的沙箱环境或者测试账号。这类限制在开发环境初始化阶段就该确认清楚别等代码写完了才发现回调配不上白白返工。另一个细节是前端路由和后端路由的冲突。/callback这个路径如果前端也占用了刷新页面可能被前端路由截走拿不到授权码。通常的处理方式是让后端处理回调、处理完之后 302 跳回前端页面或者在前端路由里显式声明这个路径走服务端。6.2 MinIO 这类对象存储用域名访问对象存储的 SDK 对域名很敏感因为它的签名计算里包含了 Host 头。你从http://127.0.0.1:9000生成的预签名 URL拿浏览器打开是能用的但一旦服务换成域名访问签名就对不上了。配置思路是在启动 MinIO 时声明域名docker run -d --name minio \ -p 9000:9000 -p 9001:9001 \ -e MINIO_DOMAINmyapp.test \ -e MINIO_ROOT_USERadmin \ -e MINIO_ROOT_PASSWORDadmin123456 \ -v /data/minio:/data \ minio/minio server /data --console-address :9001MINIO_DOMAIN设置成myapp.test存储桶就会以bucket.myapp.test这种虚拟主机风格访问而不是路径风格。这意味着你需要泛域名解析支持前面讲的 dnsmasq 方案在这里就派上用场了。Nginx 转发这一层有个容易忽略的坑AWS 签名头里可能出现带下划线的自定义头Nginx 默认会把这类头丢掉导致签名校验失败报一个让人摸不着头脑的SignatureDoesNotMatch。解决办法是在server块里加underscores_in_headers on;同时把ignore_invalid_headers off;和client_max_body_size 0;一起配上大文件上传才不会被截断。6.3 用 hosts 屏蔽干扰域名换一个干净的加载环境这是 hosts 最广为人知的用途但用法上有讲究。常见的写法有两种一种是127.0.0.1 ads.example.com另一种是0.0.0.0 ads.example.com。我更推荐后者因为它指向一个不可路由的地址连接会立刻失败而127.0.0.1会让浏览器去尝试连本机的 80 端口如果本机恰好有服务在跑可能返回一个奇怪的响应反而拖慢加载。典型可以屏蔽的目标是各类页面统计脚本、埋点上报接口、第三方广告位资源。屏蔽之后本地页面的首次加载时间经常能有肉眼可见的改善而且不会因为某个统计脚本卡住而阻塞后续资源。需要注意的是屏蔽这一类域名只在本机生效对线上环境没有任何影响。如果你在做性能分析屏蔽掉统计脚本反而会让数据失真测速之前记得先关掉。工具是用来解决问题的用错场景就是给自己添乱。6.4 让内网服务用域名替代机器名自建的代码托管服务、制品仓库、CI 面板这类内网工具默认生成的克隆地址里往往带的是机器 ID 或者内网 IP同事之间互相分享链接时很难看换台机器环境变了地址就失效。以 GitLab 为例改掉external_url配置指向一个域名然后重新执行配置加载命令# /etc/gitlab/gitlab.rb external_url http://gitlab.myapp.test改完之后在 hosts 里把gitlab.myapp.test指向对应的内网地址克隆的时候就能用git clone http://gitlab.myapp.test/group/project.git团队里所有人用同一份配置模板谁的机器上都是同样的地址交接和文档编写都轻松很多。这个思路可以复制到所有内网服务上统一的域名体系本身就是一种文档看域名就知道这个服务是干什么的。等到服务数量上到十几个的时候你会感谢当初做了这件事。7. 排查手册改完不生效的检查点7.1 按顺序排查的正确姿势遇到改了 hosts 但没生效最忌讳的是东试一下西试一下。我总结的顺序是自下而上、逐层排除每一步都能明确告诉你问题在哪一层。第一步先确认文件真的被写进去了。用编辑器重新打开 hosts 文件看一眼内容是否还在排除安全软件还原、保存失败、存到错误路径这几种情况。这一步能解决相当比例的灵异问题。第二步命令行解析验证。Linux 和 macOS 用getent hosts 域名Windows 用ping 域名。如果这里拿到的 IP 不对问题在解析层跟浏览器和服务都没关系。如果拿到的是对的直接跳到第五步。第三步检查解析顺序。Linux 上看/etc/nsswitch.conf确认files在dns前面。这一步被忽略得太多了。第四步刷新 DNS 缓存按前面的表格执行对应命令然后重新验证。如果刷新前后结果不一样说明之前一直读的是缓存。第五步检查服务本身是不是真的在监听。用curl -v http://域名看具体报什么错是连接被拒绝、超时、还是返回了 404。连接被拒绝通常是端口没起或者监听地址不对超时往往是防火墙或者监听在错误网卡上。第六步检查 Host 头透传。如果请求打到了服务但返回的内容不对或者页面跳转到了本机地址往前翻 Nginx 配置里的proxy_set_header Host。按这个顺序走大部分问题在前三步就能定位。7.2 浏览器侧的三个隐形陷阱有时候解析完全正确、服务也正常但浏览器就是不给你想要的结果。这时候问题通常在浏览器自己身上。第一个陷阱是 HTTPS 强制升级。如果你的域名后缀在 HSTS 预加载列表里浏览器会把 http 强升到 https而这个升级是内部的你在地址栏里看不到任何提示只能从 Network 面板里看到请求变成了https://。换一个.test后缀或者老老实实配上本地证书。第二个陷阱是浏览器自带的 DNS 缓存和 socket 连接池。Chromium 系浏览器有自己的解析缓存系统刷新了它不一定跟着刷新。打开chrome://net-internals/#dns点一下 Clear host cache再去#sockets把连接池清一遍很多时候立刻就好了。第三个陷阱是地址栏的搜索劫持。你输入api.myapp.test回车浏览器可能把它当成搜索词丢给了搜索引擎。判断依据是地址栏变成了搜索引擎的结果页而不是服务返回的内容。养成习惯调试时输入完整的http://api.myapp.test或者把.test这类后缀配置成不会被当作搜索关键词的前缀。7.3 常见问题速查表我把这些年遇到过的高频问题整理成了一张表遇到情况直接对号入座。现象常见原因处理方式hosts 保存后重启被还原安全软件锁定文件或文件属性只读关闭该文件的保护取消只读属性ping 能通但浏览器打不开浏览器有独立 DNS 缓存清空浏览器 host cache 和 socket 池改了完全没反应解析顺序被改成 dns 优先检查并修正 nsswitch.conf页面跳转到了 127.0.0.1Nginx 未透传 Host 头加 proxy_set_header Host $host热更新一直重连WebSocket 升级头未转发转发 Upgrade 和 Connection 头提示 host not allowed开发服务器域名白名单未放开配置 allowedHosts浏览器强制跳 https域名后缀在 HSTS 预加载列表换用 .test 后缀或配置本地证书容器内解析失败容器使用独立的 hosts用 extra_hosts 或 add-host 补记录登录成功但刷新掉线Cookie 的 Secure 或 SameSite 限制本地启用 HTTPS 或按环境区分开关大文件上传中断Nginx 请求体大小限制调整 client_max_body_size签名校验失败带下划线的请求头被丢弃开启 underscores_in_headers7.4 几个我踩过的实操心得第一个心得是每次改 hosts 之前先备份。sudo cp /etc/hosts /etc/hosts.bak花不了一秒钟但当你误删了几百行内网记录的时候这一秒钟能救命。尤其是接手别人的开发机人家的 hosts 里可能攒了几十条历史遗留记录你一个手滑全没了找都找不回来。第二个心得是给托管内容加标记。不管是脚本自动写的还是手动维护的都用显眼的注释头尾包起来比如# devkit begin 。半年后你再回头看这个文件还能一眼分清哪些是工具生成的、哪些是自己临时加的。这个习惯在多人共用一台开发机时尤其重要。第三个心得是不要过度依赖 hosts。当域名数量超过一二十个或者需要用通配符的时候就该考虑上本地 DNS 服务了。hosts 适合小而稳的场景硬撑到很复杂的规模维护成本会指数级上升。工具选型这件事早一步调整比晚一步重构要划算得多。第四个心得是把本地环境的初始化写进项目文档。我在每个新项目的 README 里都会放一段本地环境准备包含 hosts 模板、证书生成命令、需要开的端口新人照着敲十分钟就能跑起来。这件事看起来琐碎但它省掉的是团队里每个人半小时的沟通成本也是新人入职体验里最容易加分的一环。我个人在实际操作中的体会是本地环境这事没有一劳永逸的方案但有一套足够稳的套路.test后缀定域名、标记位加脚本管 hosts、Nginx 收口管端口、mkcert 管证书、dnsmasq 管泛解析。这五件事做到位后面不管项目怎么变你都不会再因为地址不对这种问题浪费时间了。
hosts文件与本地域名解析：开发环境、端口、HTTPS配置
做开发这些年我改过的 hosts 文件次数大概比提交的 commit 还多。新项目拉下来第一步往往就是在开发环境配置里把本地 hosts 改掉让api.myapp.test指向127.0.0.1而不是让代码里到处散落着127.0.0.1:8080。很多刚入行的同学第一次听到这件事会愣一下动一个系统文件就能把我编出来的域名指到本机答案是真能而且这是成本最低、依赖最少、离线也能跑的做法。这篇东西写给三类人看。第一类是刚入行、被本机地址和线上域名来回切换折腾到头晕的后端同学你大概率正在为回调地址、Cookie 域、静态资源跨域发愁。第二类是需要联调第三方登录、单点登录、本地 HTTPS 的前端同学域名的细微差别会直接决定你能不能调试成功。第三类是要带新人、想把本地开发环境做成一套可复制模板的团队负责人。我会从 hosts 的解析原理讲到三大系统的操作细节再讲到端口处理、泛域名、容器环境、常见故障排查每个环节都给出可以直接抄走的配置和脚本。全文不涉及任何外部网络的特殊玩法纯粹是本机开发环境的搭建经验。1. 本地 hosts 改动背后的真实需求拆解1.1 hosts 文件的本质一张系统级的通讯录操作系统在真正去问 DNS 服务器这个域名对应哪个 IP之前会先翻一张本地的静态表这张表就是 hosts 文件。它的结构极其简单一行一条记录格式是IP地址 主机名 [别名1 别名2 ...]中间用空格或者 Tab 分隔#开头的是注释。比如127.0.0.1 api.myapp.test这行的意思就是凡是本机要解析api.myapp.test这个名字答案就是127.0.0.1不用再往外问了。关键在于优先级这三个字。Linux 和 macOS 上解析顺序由/etc/nsswitch.conf里那一行hosts: files dns决定files排在前面就意味着先读 hosts 文件读到了就直接返回读不到才去dns那一层。Windows 的顺序是写死的同样是 hosts 优先、DNS 兜底。所以你在 hosts 里写的记录等于给本机装了一个最高优先级的解析答案任何程序走标准解析流程都会拿到它。这一点带来两个直接好处。一是离线可用你在地铁上、在客户现场没有网络照样能把整套开发环境跑起来。二是可控解析结果完全由你说了算不受运营商 DNS 缓存、不受公司内网 DNS 策略影响。很多人只知道 hosts 能屏蔽广告其实它在开发环境里的价值远大于此它是整个本地环境的地基。1.2 为什么不该直接拿 127.0.0.1 硬编码开干我最开始写项目的时候也觉得改 hosts 是多余动作代码里写死http://localhost:8080不也能跑吗直到踩了几次坑才明白这么做会在四个地方给你埋雷。第一个雷是回调地址。第三方开放平台、支付网关、单点登录服务几乎都会校验回调地址的域名白名单而且很多平台明确不接受 IP 形式的回调地址。你在本机用127.0.0.1:3000/callback去调试配置页面根本存不进去测试账号也申请不下来。换成http://app.myapp.test/callback问题当场消失因为它长得就像一个正常域名。第二个雷是 Cookie 作用域。浏览器的 Cookie 是按域绑定的localhost是一个没有顶级域的孤岛你在localhost上设的 Cookie子域之间没法共享Domain.myapp.test这种写法在 localhost 上完全失效。想把登录态存主域、子系统读主域这套逻辑在本地跑通就必须有真实域名。第三个雷是跨域策略。前后端分离的项目前端跑在 5173、后端跑在 8080如果两边都用127.0.0.1只是端口不同浏览器判定为同源你反而测不出真实的跨域场景。等到上线才发现 CORS 配置有问题那就晚了。第四个雷是环境变量污染。代码里散落着几十处硬编码地址某天要把测试环境切到预发环境你得全局搜索替换一遍漏一处就出事。统一用域名之后改配置只需要动一个地方。1.3 什么时候其实不该改 hosts也不是所有场景都值得动 hosts。如果你的项目就是一个纯前端静态页面没有任何后端交互也不涉及登录态和回调那直接用localhost:5173是最快的方式多此一举。还有一种情况是团队里有人图省事把所有线上域名在 hosts 里指到本机结果某天排查线上问题时忘了自己改过本地复现出来的现象和真实线上对不上白白浪费半天。我的习惯是给托管片段加明显的注释头尾标记并且只写.test这类本地专用后缀绝不把线上域名往 hosts 里写。再有就是移动端真机调试。手机系统的 hosts 文件没有 root 权限改不了硬凑也没意义。这种场景更适合在路由器上配一条本地 DNS 记录或者老老实实在手机上装一个能指定测试环境的包。方向选错了后面所有努力都是白费。2. 三个系统下的 hosts 文件操作细节2.1 Windows权限、编码与扩展名三个坑Windows 的 hosts 路径是C:\Windows\System32\drivers\etc\hosts这个文件从 Vista 开始就受系统保护普通权限打开是只读的。最稳的打开方式是以管理员身份启动编辑器比如在开始菜单搜到 VS Code 或者 Notepad右键以管理员身份运行然后在编辑器里打开这个路径。用命令行的话管理员权限的 CMD 里执行notepad C:\Windows\System32\drivers\etc\hosts也可以重点是一定要管理员。第一个坑是扩展名。如果你新建一个文本文件改完再拖进这个目录很容易被存成hosts.txt而系统只认没有扩展名的hosts。用记事本另存为的时候文件名那一栏要加英文双引号包起来写成hosts才能避免被自动补上.txt。第二个坑是编码。老版本记事本默认存成带 BOM 的 UTF-8部分情况下会导致解析异常表现为某几条记录莫名其妙不生效。现在 Win10 以后的记事本默认是无 BOM 的 UTF-8问题少了很多但如果你用一些老旧编辑器记得手动选 UTF-8 无 BOM 或者纯 ASCII。只写英文域名和 IP 的话其实 ANSI 最省事。第三个坑是安全软件。一些终端防护类软件会把 hosts 文件锁定你保存的瞬间不报错重启之后记录全没了或者直接被还原成系统默认内容。判断方法是看文件属性里只读有没有被勾上以及保存后用文本编辑器再打开确认一眼。如果每次都被还原就得去安全软件里把这个文件的保护关掉。改完之后立刻验证ping api.myapp.test看返回的 IP 是不是你写的那一个。记住nslookup不会读 hosts 文件它直接去问 DNS用它验证会得到解析失败的假象别被误导。2.2 macOS 与 Linuxsudo、nsswitch 与解析顺序macOS 和 Linux 的路径都是/etc/hosts改的时候需要提权sudo vim /etc/hosts是最常见的姿势。文件格式和 Windows 完全一样也是IP 域名一行一条。写 IPv6 的话用::1 api.myapp.test。Linux 上值得多看一眼的是/etc/nsswitch.conf。这个文件里有一行大概长这样hosts: files dns myhostname。files排在dns前面hosts 文件才有优先权。有些容器镜像或者精简系统会把它改成hosts: dns files这时候你在 hosts 里写的记录会被 DNS 结果覆盖表现为改了完全没用。遇到反常情况先cat /etc/nsswitch.conf | grep hosts确认一眼。验证命令上Linux 和 macOS 推荐用getent hosts api.myapp.test它走的是完整的系统解析链路会读 hosts结果最可信。macOS 上还可以用dscacheutil -q host -a name api.myapp.test来查缓存里的解析结果。dig和nslookup同样是绕过 hosts 的只用来排查 DNS 侧的问题别用来验证 hosts。另外提一句域名解析是不区分大小写的你写API.MyApp.Test和api.myapp.test效果一样没必要纠结。但主机名后面千万不要手抖多打空格、多打中文标点这些细节会直接导致那一行被解析器忽略而且不报错非常难查。2.3 改完必须执行的缓存刷新命令改完 hosts 只是第一步操作系统和浏览器各自都缓存了 DNS 结果不刷新的话你看到的现象可能和实际配置不一致。三个平台的刷新命令我整理成了一张表建议直接存进笔记。系统刷新命令备注Windowsipconfig /flushdns需要普通权限即可macOS 10.10sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder两条一起执行Linux (systemd-resolved)sudo resolvectl flush-caches老版本用systemd-resolve --flush-cachesLinux (nscd)sudo systemctl restart nscd装了 nscd 才需要浏览器 (Chromium 系)打开chrome://net-internals/#dns点 Clear host cache顺手清一下 socket 池刷新完别急着开页面先ping一下确认解析再动浏览器。这套顺序能帮你把到底是解析问题还是服务问题当场分开少绕很多弯路。还有个容易被忽略的点Windows 上如果开了 Hyper-V 或者装了 Docker Desktop会有虚拟网卡参与网络栈极个别情况下 hosts 的改动要等几秒才生效。如果你刚改完就测等五秒再试一次不要立刻下结论。3. 域名选型与端口处理hosts 搞不定的那部分3.1 用什么后缀做本地域名更安全本地域名不是随便编的用错了后缀会带来一堆莫名其妙的麻烦。RFC 6761 明确保留了几个永远不会被注册的顶级域.test、.example、.invalid、.localhost。其中.test是社区里做本地开发最通用的选择我强烈推荐统一用它。为什么不用.local这个后缀在 RFC 6762 里被分配给 mDNS也就是苹果的 BonjourmacOS 和部分 Linux 发行版会用组播去解析.local结尾的名字。你在 hosts 里写一条127.0.0.1 printer.local有时候会被 mDNS 抢先响应表现就是解析结果时好时坏非常折磨人。为什么不用.dev这是新手最容易踩的坑。整个.dev顶级域都在浏览器的 HSTS 预加载列表里意味着浏览器对你的.dev域名强制走 HTTPS你写http://app.dev会被浏览器内部升级成https://app.dev如果本地没有配置证书直接报连接错误。你要么老老实实配本地 HTTPS 证书要么干脆换后缀。.com、.cn这类真实后缀更别碰一是理论上有和真实站点撞车的可能二是很多企业内网会自动跳转到公司门户排查起来费时费力。结论很简单本地开发统一用.test这是最省心的答案。3.2 hosts 不能带端口那端口怎么办这是被问得最多的一个问题hosts 文件配置域名可以加端口吗答案是明确不行。hosts 文件工作在域名解析层它只负责把名字翻译成IP 地址压根不知道端口这回事。你写127.0.0.1:8080 api.myapp.test整个文件都会解析异常。所以带端口的写法只能是http://api.myapp.test:8080端口还得写在 URL 里。如果端口是 80 或者 443浏览器允许省略写http://api.myapp.test就等于 80 端口。这就引出了一个非常实用的思路把本地服务的监听端口挪到 80 和 443 上域名后面就不用带端口了。但在 Windows 上80 端口经常已经被系统组件或者某些后台服务占用服务起不来还报一个权限不足或者地址已被占用。先排查占用情况netstat -ano | findstr :80拿到最后一列的 PID再去任务管理器里看是哪个进程。确认能腾出来之后再让服务监听 80。如果 80 端口腾不出来还有一个更优雅的方案见下一节。3.3 用 Nginx 做统一入口把端口藏起来我现在的标准做法是所有本地服务都跑在高位端口3000、8080、9000 之类前面挂一个 Nginx 监听 80 和 443按域名转发到对应的后端。这样你访问http://api.myapp.test就是干净的带不带端口这件事从此不用再想。# 按域名分发一个入口管所有本地服务 server { listen 80; server_name api.myapp.test; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } } server { listen 80; server_name web.myapp.test; location / { proxy_pass http://127.0.0.1:5173; proxy_set_header Host $host; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; } }这里有几个细节必须说清楚。proxy_set_header Host $host这行千万别省它的作用是把浏览器请求里的原始域名透传给后端。少了这一行后端拿到的是127.0.0.1:8080如果它要用这个值拼回调地址、拼跳转链接生成出来的 URL 就是错的你会看到页面莫名其妙跳到了本机地址。第二段配置里的Upgrade和Connection两行是给前端热更新用的Vite 和 webpack 的 HMR 都走 WebSocket不配这两行热更新会一直重连失败控制台里刷一片报错。这是很多人配完 Nginx 之后页面能打开但热更新失效的根因。还有个细节是X-Forwarded-Proto。本地走的是 http但某些后端框架会根据这个头判断请求协议用来决定 Cookie 要不要加 Secure 标记。老老实实传上去能省掉一类本地登录成功但刷新就掉线的怪问题。4. 从能解析到能调试前端与后端的联调配置4.1 Vite 与 webpack devServer 的 allowedHosts 坑改完 hosts 之后打开浏览器很多人会遇到这样一条报错Blocked request. This host (web.myapp.test) is not allowed.这不是 hosts 的问题而是 Vite 4.0 之后新增的安全检查。开发服务器默认只接受localhost和 IP 形式的 Host 头你用了自定义域名就会被拦下来。解决办法是在vite.config.js里显式放行import { defineConfig } from vite export default defineConfig({ server: { host: 0.0.0.0, port: 5173, strictPort: true, allowedHosts: [.myapp.test, localhost] } })allowedHosts传入以点开头的后缀可以一次性放行整个子域比逐个列域名省事。webpack 侧的对应配置是devServer.allowedHosts旧版本用的是disableHostCheck: true写法上略有区别但道理一样告诉开发服务器这个域名是我自己人。host: 0.0.0.0也值得单独说一句。默认情况下 Vite 只监听回环地址本机访问没问题但如果你要用手机连同一个 Wi-Fi 做真机预览或者用 Docker 跑开发服务就必须放开到0.0.0.0否则外部怎么都连不上。放开之后记得别在公共网络环境下开这个服务同一网段的人能直接访问到你的代码。4.2 本地 HTTPS 与受信证书有一类功能在 http 下根本测不了。比如浏览器的地理定位、摄像头调用、Service Worker 注册、部分 OAuth 平台的回调都要求页面运行在安全上下文里。本地要凑齐 HTTPS就要有一张浏览器认的证书。以前的做法是自己用 openssl 生成自签证书然后每次都被浏览器拦下来点继续访问而且接口请求经常因为证书不受信直接失败。现在我的标准工具是 mkcert它会在本机装一个根证书到系统信任区再用这个根证书签发你的本地域名证书浏览器打开就是绿锁没有任何警告。# 安装后先初始化根证书 mkcert -install # 一条命令生成覆盖你需要的所有名字的证书 mkcert -cert-file ./certs/myapp.pem \ -key-file ./certs/myapp-key.pem \ myapp.test *.myapp.test localhost 127.0.0.1 ::1注意*.myapp.test必须加引号否则 shell 会尝试做通配符展开把那几个字符解释成当前目录下的文件名生成出来的证书就缺了泛域名。证书生成好之后把cert和key两个路径配到 Nginx 的ssl_certificate和ssl_certificate_key上或者配到 Vite 的server.https里都行。这里有个团队协作的坑mkcert 生成的根证书是每台机器独立的没法共享给同事用。所以别把证书文件提交到仓库里让大家共用正确做法是在项目 README 里写清楚执行mkcert -install和下面这条命令让每个人在自己机器上生成一份。证书文件本身要加进.gitignore。4.3 Cookie 域、SameSite 与跨子域登录态把主域和各个子域都写进 hosts全部指向127.0.0.1这是本地调多系统登录的标准姿势127.0.0.1 myapp.test 127.0.0.1 auth.myapp.test 127.0.0.1 app.myapp.test 127.0.0.1 admin.myapp.test这样做的直接收益是 Cookie 可以设为Domain.myapp.test浏览器会把它带到所有子域上单点登录在本地就能跑通。如果全是localhost这套逻辑根本没法验证。但 Cookie 还有两个属性经常在本地翻车。一个是Secure加了它浏览器只允许在 HTTPS 下存储和发送。本地跑 http 时Set-Cookie里带Secure的响应会被浏览器直接丢弃表现就是登录接口返回 200 但 Cookie 没存下来。要么本地配上 HTTPS要么在开发环境把Secure关掉——我倾向于用配置区分别在代码里硬编码。另一个是SameSite。SameSiteNone必须和Secure配对使用在 http 下不生效。如果你的系统需要跨站带 Cookie本地测试就绕不开 HTTPS 这条路。这就是为什么前面花那么大篇幅讲 mkcert它不是一个可选项而是某些功能调试的必经之路。5. 泛域名、多域名与团队协作的工程化做法5.1 dnsmasq 实现泛解析摆脱逐条维护项目稍微大一点域名数量就压不住了api.test、api-v2.test、user-api.test、order-api.test……每加一个微服务就要在 hosts 里加一行还得通知所有同事跟着加非常低效。*.myapp.test这种通配写法在 hosts 文件里是不支持的解析器会把星号当普通字符处理写了也没用。解决办法是引入一个本地 DNS 服务让它在域名匹配不上时返回一个固定地址。dnsmasq 是最常用的那个配置一行就够# /usr/local/etc/dnsmasq.conf address/.myapp.test/127.0.0.1然后在系统 DNS 设置里把127.0.0.1加为第一顺位的解析服务器这样所有以.myapp.test结尾的域名都会拿到127.0.0.1再也不用管具体子域叫什么。macOS 上还有一个更轻的写法不需要装任何服务。只要新建/etc/resolver/test文件内容是nameserver 127.0.0.1系统就会把.test后缀的查询全部交给本机的 DNS 服务。当然前提是你本机确实跑着一个 DNS 服务。Windows 没有这类内置机制比较现实的做法是项目初始化脚本自动往 hosts 里追加需要的记录或者干脆装个支持泛解析的本地 DNS 服务。别硬扛工具解决的问题就用工具解决。5.2 用 hosts 管理工具做方案切换与模板手改/etc/hosts最大的问题是没法版本化、没法快速切换。今天调 A 项目明天调 B 项目来回注释和取消注释特别容易出错。SwitchHosts 这类工具能明显改善体验。它让你把不同项目的 hosts 内容存成独立的方案随时勾选启用或关闭还支持从远程 URL 拉取配置。我一般的做法是在项目仓库里放一个docs/hosts.example文件内容就是当前项目需要的全部记录新人 clone 下来复制到工具里勾上就完事。这个hosts.example文件要遵守两个约定。一是带上说明注释写清楚每条记录对应哪个服务、跑在哪个端口。二是只放.test后缀的域名不掺任何线上地址避免有人误启用之后把真实流量引到本机。下面是我常用的模板结构# myapp 本地开发 hosts # api - 后端主服务 (8080) # web - 前端开发服务器 (5173) # admin - 后台管理系统 (8081) 127.0.0.1 myapp.test 127.0.0.1 api.myapp.test 127.0.0.1 web.myapp.test 127.0.0.1 admin.myapp.test5.3 Docker 容器与 WSL 里的 hosts 是另一份这一步坑了很多人你把宿主机的 hosts 改好了浏览器访问正常但跑在容器里的服务访问同一个域名却解析失败。原因很简单容器有自己独立的网络命名空间/etc/hosts是容器镜像里那一份跟宿主机的完全没关系。Docker Compose 里可以用extra_hosts补上services: api: image: myapp/api:dev extra_hosts: - db.myapp.test:host.docker.internal - redis.myapp.test:host.docker.internalhost.docker.internal是 Docker Desktop 提供的特殊主机名指向宿主机。在 Linux 上如果这个特殊域名不可用可以显式指定宿主机的网桥地址或者在docker run时加--add-hostdb.myapp.test:172.17.0.1。WSL2 又是另一套逻辑。WSL 里的/etc/hosts是系统启动时自动生成的你手动改的内容在wsl --shutdown之后会被覆盖。想让它保留下来需要关掉自动生成# /etc/wsl.conf [network] generateHosts false generateResolvConf false关掉generateResolvConf之后要自己维护/etc/resolv.conf写一个能用的 DNS 地址进去否则整个 WSL 会断网。这两项改完执行wsl --shutdown重启生效之后再改 hosts 就不会被冲掉了。5.4 一个带标记位的一键切换脚本既然要频繁改就写个脚本用注释标记圈出托管区域脚本只负责替换这两行标记之间的内容不会碰你自己加的其他记录。#!/usr/bin/env bash set -euo pipefail HOSTS_FILE/etc/hosts TEMPLATE./hosts.dev.txt BEGIN# devkit begin END# devkit end tmp_file$(mktemp) trap rm -f $tmp_file EXIT # 删掉旧的托管段落保留其他所有内容 awk -v b$BEGIN -v e$END $0 b { skip 1; next } $0 e { skip 0; next } !skip { print } $HOSTS_FILE $tmp_file # 追加新的托管段落 { echo $BEGIN cat $TEMPLATE echo $END } $tmp_file sudo cp $tmp_file $HOSTS_FILE # 按平台刷新缓存 case $(uname -s) in Darwin) sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder ;; Linux) sudo resolvectl flush-caches 2/dev/null || true ;; esac echo hosts 已更新这个脚本的价值在于幂等。反复执行不会重复追加记录也不会把你手动加的临时条目删掉因为 awk 只过滤标记之间的内容。trap那行保证脚本中途出错时临时文件会被清理不会在/tmp里堆一堆垃圾。团队里跑起来比挨个口头交代记得加这条靠谱得多。6. 四类典型场景的落地配置6.1 第三方登录回调的本地调试做第三方登录联调时平台后台一般要求你填回调域名很多平台不接受 IP也不接受带端口的形式。本地调试的思路是把回调地址填成http://app.myapp.test/callback同时在 hosts 里把这几个域名指向本机再在本地服务里拦截这个路径处理授权码。有一个细节要注意部分平台会校验回调域名的主域名是否在备案白名单内这种情况下你没法拿一个假域名糊弄过去只能走平台的沙箱环境或者测试账号。这类限制在开发环境初始化阶段就该确认清楚别等代码写完了才发现回调配不上白白返工。另一个细节是前端路由和后端路由的冲突。/callback这个路径如果前端也占用了刷新页面可能被前端路由截走拿不到授权码。通常的处理方式是让后端处理回调、处理完之后 302 跳回前端页面或者在前端路由里显式声明这个路径走服务端。6.2 MinIO 这类对象存储用域名访问对象存储的 SDK 对域名很敏感因为它的签名计算里包含了 Host 头。你从http://127.0.0.1:9000生成的预签名 URL拿浏览器打开是能用的但一旦服务换成域名访问签名就对不上了。配置思路是在启动 MinIO 时声明域名docker run -d --name minio \ -p 9000:9000 -p 9001:9001 \ -e MINIO_DOMAINmyapp.test \ -e MINIO_ROOT_USERadmin \ -e MINIO_ROOT_PASSWORDadmin123456 \ -v /data/minio:/data \ minio/minio server /data --console-address :9001MINIO_DOMAIN设置成myapp.test存储桶就会以bucket.myapp.test这种虚拟主机风格访问而不是路径风格。这意味着你需要泛域名解析支持前面讲的 dnsmasq 方案在这里就派上用场了。Nginx 转发这一层有个容易忽略的坑AWS 签名头里可能出现带下划线的自定义头Nginx 默认会把这类头丢掉导致签名校验失败报一个让人摸不着头脑的SignatureDoesNotMatch。解决办法是在server块里加underscores_in_headers on;同时把ignore_invalid_headers off;和client_max_body_size 0;一起配上大文件上传才不会被截断。6.3 用 hosts 屏蔽干扰域名换一个干净的加载环境这是 hosts 最广为人知的用途但用法上有讲究。常见的写法有两种一种是127.0.0.1 ads.example.com另一种是0.0.0.0 ads.example.com。我更推荐后者因为它指向一个不可路由的地址连接会立刻失败而127.0.0.1会让浏览器去尝试连本机的 80 端口如果本机恰好有服务在跑可能返回一个奇怪的响应反而拖慢加载。典型可以屏蔽的目标是各类页面统计脚本、埋点上报接口、第三方广告位资源。屏蔽之后本地页面的首次加载时间经常能有肉眼可见的改善而且不会因为某个统计脚本卡住而阻塞后续资源。需要注意的是屏蔽这一类域名只在本机生效对线上环境没有任何影响。如果你在做性能分析屏蔽掉统计脚本反而会让数据失真测速之前记得先关掉。工具是用来解决问题的用错场景就是给自己添乱。6.4 让内网服务用域名替代机器名自建的代码托管服务、制品仓库、CI 面板这类内网工具默认生成的克隆地址里往往带的是机器 ID 或者内网 IP同事之间互相分享链接时很难看换台机器环境变了地址就失效。以 GitLab 为例改掉external_url配置指向一个域名然后重新执行配置加载命令# /etc/gitlab/gitlab.rb external_url http://gitlab.myapp.test改完之后在 hosts 里把gitlab.myapp.test指向对应的内网地址克隆的时候就能用git clone http://gitlab.myapp.test/group/project.git团队里所有人用同一份配置模板谁的机器上都是同样的地址交接和文档编写都轻松很多。这个思路可以复制到所有内网服务上统一的域名体系本身就是一种文档看域名就知道这个服务是干什么的。等到服务数量上到十几个的时候你会感谢当初做了这件事。7. 排查手册改完不生效的检查点7.1 按顺序排查的正确姿势遇到改了 hosts 但没生效最忌讳的是东试一下西试一下。我总结的顺序是自下而上、逐层排除每一步都能明确告诉你问题在哪一层。第一步先确认文件真的被写进去了。用编辑器重新打开 hosts 文件看一眼内容是否还在排除安全软件还原、保存失败、存到错误路径这几种情况。这一步能解决相当比例的灵异问题。第二步命令行解析验证。Linux 和 macOS 用getent hosts 域名Windows 用ping 域名。如果这里拿到的 IP 不对问题在解析层跟浏览器和服务都没关系。如果拿到的是对的直接跳到第五步。第三步检查解析顺序。Linux 上看/etc/nsswitch.conf确认files在dns前面。这一步被忽略得太多了。第四步刷新 DNS 缓存按前面的表格执行对应命令然后重新验证。如果刷新前后结果不一样说明之前一直读的是缓存。第五步检查服务本身是不是真的在监听。用curl -v http://域名看具体报什么错是连接被拒绝、超时、还是返回了 404。连接被拒绝通常是端口没起或者监听地址不对超时往往是防火墙或者监听在错误网卡上。第六步检查 Host 头透传。如果请求打到了服务但返回的内容不对或者页面跳转到了本机地址往前翻 Nginx 配置里的proxy_set_header Host。按这个顺序走大部分问题在前三步就能定位。7.2 浏览器侧的三个隐形陷阱有时候解析完全正确、服务也正常但浏览器就是不给你想要的结果。这时候问题通常在浏览器自己身上。第一个陷阱是 HTTPS 强制升级。如果你的域名后缀在 HSTS 预加载列表里浏览器会把 http 强升到 https而这个升级是内部的你在地址栏里看不到任何提示只能从 Network 面板里看到请求变成了https://。换一个.test后缀或者老老实实配上本地证书。第二个陷阱是浏览器自带的 DNS 缓存和 socket 连接池。Chromium 系浏览器有自己的解析缓存系统刷新了它不一定跟着刷新。打开chrome://net-internals/#dns点一下 Clear host cache再去#sockets把连接池清一遍很多时候立刻就好了。第三个陷阱是地址栏的搜索劫持。你输入api.myapp.test回车浏览器可能把它当成搜索词丢给了搜索引擎。判断依据是地址栏变成了搜索引擎的结果页而不是服务返回的内容。养成习惯调试时输入完整的http://api.myapp.test或者把.test这类后缀配置成不会被当作搜索关键词的前缀。7.3 常见问题速查表我把这些年遇到过的高频问题整理成了一张表遇到情况直接对号入座。现象常见原因处理方式hosts 保存后重启被还原安全软件锁定文件或文件属性只读关闭该文件的保护取消只读属性ping 能通但浏览器打不开浏览器有独立 DNS 缓存清空浏览器 host cache 和 socket 池改了完全没反应解析顺序被改成 dns 优先检查并修正 nsswitch.conf页面跳转到了 127.0.0.1Nginx 未透传 Host 头加 proxy_set_header Host $host热更新一直重连WebSocket 升级头未转发转发 Upgrade 和 Connection 头提示 host not allowed开发服务器域名白名单未放开配置 allowedHosts浏览器强制跳 https域名后缀在 HSTS 预加载列表换用 .test 后缀或配置本地证书容器内解析失败容器使用独立的 hosts用 extra_hosts 或 add-host 补记录登录成功但刷新掉线Cookie 的 Secure 或 SameSite 限制本地启用 HTTPS 或按环境区分开关大文件上传中断Nginx 请求体大小限制调整 client_max_body_size签名校验失败带下划线的请求头被丢弃开启 underscores_in_headers7.4 几个我踩过的实操心得第一个心得是每次改 hosts 之前先备份。sudo cp /etc/hosts /etc/hosts.bak花不了一秒钟但当你误删了几百行内网记录的时候这一秒钟能救命。尤其是接手别人的开发机人家的 hosts 里可能攒了几十条历史遗留记录你一个手滑全没了找都找不回来。第二个心得是给托管内容加标记。不管是脚本自动写的还是手动维护的都用显眼的注释头尾包起来比如# devkit begin 。半年后你再回头看这个文件还能一眼分清哪些是工具生成的、哪些是自己临时加的。这个习惯在多人共用一台开发机时尤其重要。第三个心得是不要过度依赖 hosts。当域名数量超过一二十个或者需要用通配符的时候就该考虑上本地 DNS 服务了。hosts 适合小而稳的场景硬撑到很复杂的规模维护成本会指数级上升。工具选型这件事早一步调整比晚一步重构要划算得多。第四个心得是把本地环境的初始化写进项目文档。我在每个新项目的 README 里都会放一段本地环境准备包含 hosts 模板、证书生成命令、需要开的端口新人照着敲十分钟就能跑起来。这件事看起来琐碎但它省掉的是团队里每个人半小时的沟通成本也是新人入职体验里最容易加分的一环。我个人在实际操作中的体会是本地环境这事没有一劳永逸的方案但有一套足够稳的套路.test后缀定域名、标记位加脚本管 hosts、Nginx 收口管端口、mkcert 管证书、dnsmasq 管泛解析。这五件事做到位后面不管项目怎么变你都不会再因为地址不对这种问题浪费时间了。
