How to edit /etc/hosts without breaking your local setup

如何在不破坏本地配置的情况下编辑 /etc/hosts

Most people open /etc/hosts, change one line, refresh the browser, and hope. That works until it does not. Then you spend twenty minutes on Permission denied, a forgotten DNS flush, or a commented line from last week that is still active. This is a simple workflow that keeps hosts edits boring. 大多数人打开 /etc/hosts，修改一行，刷新浏览器，然后祈祷生效。这种方法在失效之前确实管用。一旦失效，你可能要花二十分钟去处理“权限拒绝”、忘记刷新 DNS，或者上周注释掉的一行代码依然生效等问题。以下是一个简单的工作流，让修改 hosts 文件变得不再折腾。

What the hosts file does

hosts 文件的作用

When your machine resolves a name like myapp.test, it can use a local override before public DNS. Common cases: 当你的机器解析像 myapp.test 这样的域名时，它可以在公共 DNS 之前使用本地覆盖。常见场景包括：

Point myapp.test to 127.0.0.1 for local work
将 myapp.test 指向 127.0.0.1 以进行本地开发
Point a real domain at a staging IP before DNS cutover
在 DNS 切换前将真实域名指向测试环境 IP
Temporarily block a host with 0.0.0.0
使用 0.0.0.0 临时屏蔽某个主机
Give services readable names instead of raw IPs
为服务提供可读的名称，而不是直接使用 IP

The idea is simple. The mess comes from how people edit and apply it. 原理很简单，但混乱往往源于人们编辑和应用它的方式。

A workflow that holds up

一个稳健的工作流

1. Do not treat /etc/hosts as your only copy 1. 不要把 /etc/hosts 当作唯一的副本

Keep a file you own: ~/dev/hosts/personal.hosts Or one file per project / client. Edit that. Apply it on purpose. 保留一份你自己的文件：~/dev/hosts/personal.hosts，或者为每个项目/客户保留一个文件。编辑这些文件，并有意识地应用它们。

2. Edit the copy, then copy it into place 2. 编辑副本，然后将其覆盖到系统路径

macOS / Linux:

code ~/dev/hosts/personal.hosts
sudo cp /etc/hosts "/etc/hosts.bak.$(date +%Y%m%d-%H%M%S)"
sudo cp ~/dev/hosts/personal.hosts /etc/hosts

Windows: edit your copy, back up the live file, then replace: C:\Windows\System32\drivers\etc\hosts. You need admin rights for the live file. That is normal. Windows：编辑你的副本，备份当前文件，然后替换：C:\Windows\System32\drivers\etc\hosts。你需要管理员权限来操作该文件，这是正常的。

3. Flush DNS every time you apply 3. 每次应用后都要刷新 DNS

Make this part of the apply step, not a later panic search. 将其作为应用步骤的一部分，而不是事后惊慌失措地去搜索。

macOS: sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder
Windows (Admin): ipconfig /flushdns
Linux (systemd-resolved): sudo resolvectl flush-caches

4. Verify in the terminal before the browser 4. 在浏览器之前，先在终端验证

ping -c 1 myapp.test # Linux: getent hosts myapp.test 终端显示 IP 正确，但浏览器页面不对？停止修改 hosts。检查浏览器 DNS、HTTPS、重定向或 HSTS。

5. Avoid two active lines for the same hostname 5. 避免同一个主机名有两行生效的配置

This breaks people constantly: 这经常导致问题： 10.0.0.5 www.client.com 127.0.0.1 www.client.com

Pick one. Comment the other, or better, keep separate profile files and swap the whole file. 二选一。注释掉另一行，或者更好的做法是，保留独立的配置文件并替换整个文件。

Example: local frontend + API 示例：本地前端 + API 127.0.0.1 shop.test 127.0.0.1 api.shop.test

Frontend env: NEXT_PUBLIC_API_URL=http://api.shop.test API env: APP_URL=http://api.shop.test

Then: Apply hosts -> Flush DNS -> Confirm with ping / getent -> Open the browser. Only then debug CORS, cookies, or TLS. Hosts bugs and app bugs look the same in a tab. Split them. 然后：应用 hosts -> 刷新 DNS -> 使用 ping / getent 确认 -> 打开浏览器。只有这样之后再去调试 CORS、Cookie 或 TLS。Hosts 问题和应用问题在浏览器标签页中看起来是一样的，请将它们区分开来。

Team onboarding

团队入职配置

If your README says “paste these 12 lines into hosts,” configs will drift. Better: Commit a hosts.example, add a short apply script, and say which environment the file is for (local, staging, etc.). Goal: new laptop works in a few minutes, not after three Slack threads. 如果你的 README 写着“把这 12 行粘贴到 hosts 里”，配置最终会变得混乱。更好的做法是：提交一个 hosts.example，添加一个简短的应用脚本，并说明该文件对应的环境（本地、测试等）。目标是：新电脑几分钟内就能配置好，而不是在 Slack 上讨论半天。

Short version

简要总结

Edit a file you own
编辑你自己的文件
Back up, then copy into the system hosts path
备份，然后复制到系统 hosts 路径
Flush DNS
刷新 DNS
Check resolution in the terminal
在终端检查解析结果
Keep one active mapping per hostname
每个主机名只保留一个生效的映射

That is enough for most local and staging work. If you are changing hosts several times a day across clients, automate the swap with a script or a small hosts manager. The process above still matters either way. 这对大多数本地和测试工作来说已经足够了。如果你每天需要在不同客户之间多次切换 hosts，请使用脚本或小型 hosts 管理工具实现自动化。无论如何，上述流程依然至关重要。