How to switch local and staging domains with the hosts file

查看原文 / View Original 编辑 / Edit

How to switch local and staging domains with the hosts file

如何使用 hosts 文件在本地和测试域名之间切换

You want shop.test on localhost during the day, then the real client domain pointed at staging, then maybe the same domain pointed at a new server before DNS moves. You do not need dnsmasq for that. You need a clean way to switch mappings without leaving three conflicting lines in /etc/hosts. 你可能白天希望 shop.test 指向本地，接着希望真实的客户域名指向测试环境，甚至在 DNS 迁移前将同一域名指向新服务器。你不需要为此安装 dnsmasq，你只需要一种简洁的方法来切换映射，而不是在 /etc/hosts 中留下三行相互冲突的记录。

Why one big hosts file fails

为什么单一的 hosts 文件行不通

After a few months it often looks like this: 几个月后，它通常会变成这样：

127.0.0.1 shop.test
127.0.0.1 api.shop.test
# 203.0.113.10 www.client.com
10.0.0.5 www.client.com
127.0.0.1 www.client.com

Same hostname, several intentions. The browser will not tell you which line won. It just resolves something. Comments help for a day. They do not help when you are tired and switching contexts. 同一个主机名，多种意图。浏览器不会告诉你哪一行生效了，它只会随机解析一个。注释或许能管用一天，但当你疲惫不堪或频繁切换工作环境时，它们就没用了。

Use profiles instead of comments

使用配置文件（Profiles）代替注释

Keep separate files. Only one is active at a time for a given hostname. Example layout: 保持文件分离。对于给定的主机名，同一时间只激活一个文件。示例布局如下：

~/dev/hosts-profiles/
  local
  staging
  cutover

local

127.0.0.1 shop.test
127.0.0.1 api.shop.test
127.0.0.1 admin.shop.test

staging

203.0.113.40 www.client.com
203.0.113.40 api.client.com

cutover (pre-DNS migration test)

198.51.100.20 www.client.com
198.51.100.20 api.client.com

Apply a profile

应用配置文件

macOS / Linux:

PROFILE=staging
sudo cp /etc/hosts "/etc/hosts.bak.$(date +%Y%m%d-%H%M%S)"
sudo cp ~/dev/hosts-profiles/$PROFILE /etc/hosts

Then flush DNS for your OS. 然后刷新操作系统的 DNS。

Windows: same idea. Keep profile files, back up the live hosts file, copy the profile over: C:\Windows\System32\drivers\etc\hosts. Then: ipconfig /flushdns Windows: 思路相同。保留配置文件，备份当前的 hosts 文件，然后覆盖：C:\Windows\System32\drivers\etc\hosts。接着执行：ipconfig /flushdns。

Small bash helper

一个简单的 Bash 辅助脚本

#!/usr/bin/env bash
set -euo pipefail
PROFILE="${1:?usage: hosts-use <profile>}"
SRC="$HOME/dev/hosts-profiles/$PROFILE"
[[ -f "$SRC" ]] || { echo "missing $SRC"; exit 1; }

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

# macOS. Swap this block on Windows/Linux.
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder
echo "Active hosts profile: $PROFILE"

Usage: ./hosts-use local / ./hosts-use staging 用法：./hosts-use local / ./hosts-use staging

Optional: base file + project overlay

可选：基础文件 + 项目覆盖

If you want personal localhost names plus project-specific domains: 如果你既想要个人的本地主机名，又想要项目特定的域名：

~/dev/hosts-profiles/
  _base
  project-shop-local
  project-shop-staging

Apply with: 使用以下命令应用：

cat ~/dev/hosts-profiles/_base \
    ~/dev/hosts-profiles/project-shop-staging \
    | sudo tee /etc/hosts >/dev/null

Keep _base small. Put production hostnames only in the project overlay so they are easy to turn off. 保持 _base 文件精简。只在项目覆盖文件中放入生产环境的主机名，这样更容易关闭它们。

Pre-DNS cutover checklist

DNS 迁移前的检查清单

This is one of the best uses of hosts: 这是 hosts 文件最好的用途之一：

  1. Put the production hostnames on the new server IP in a cutover profile. 将生产环境主机名指向新服务器 IP，放入 cutover 配置文件中。
  2. Apply the profile and flush DNS. 应用该配置并刷新 DNS。
  3. Test login, cookies, HTTPS, redirects, anything that depends on the Host header. 测试登录、Cookie、HTTPS、重定向以及任何依赖 Host 头的项目。
  4. Switch back when you are done. 完成后切换回来。

Write the rollback next to the migration checklist. You will want it on cutover night. 把回滚方案写在迁移清单旁边，在迁移当晚你会用得上的。

Docker caveat

Docker 注意事项

Hosts on your laptop affect the browser on your laptop. Processes inside containers usually use Docker DNS, not your host /etc/hosts. 你笔记本上的 hosts 文件会影响你笔记本上的浏览器。容器内的进程通常使用 Docker DNS，而不是宿主机的 /etc/hosts。

  • Browser to shop.test on the host: host hosts file. 宿主机浏览器访问 shop.test：使用宿主机 hosts 文件。
  • Container to another container: Compose service names or extra_hosts. 容器访问容器：使用 Compose 服务名或 extra_hosts。

Do not debug the wrong layer. 不要在错误的层级上进行调试。

After every switch

每次切换后

# What does the OS resolve?
getent hosts www.client.com
# macOS alternative:
# dscacheutil -q host -a name www.client.com

# What is in the file?
grep -n "www.client.com" /etc/hosts

If the terminal IP is wrong, fix hosts first. Do not dig into the app yet. 如果终端显示的 IP 不对，先修复 hosts 文件，不要急着去排查应用。

When hosts profiles stop being enough

当 hosts 配置文件不再够用时

Move to dnsmasq, CoreDNS, or company DNS when you need: 当你需要以下功能时，请转向 dnsmasq、CoreDNS 或公司 DNS：

  • lots of wildcards (大量通配符)
  • many services added every week (每周新增大量服务)
  • one shared dynamic map for a whole team (整个团队共享一个动态映射)

Until then, separate profile files beat a single commented hosts file. Start with three files: local for your .test domains, staging for client staging IPs, cutover left empty until migration week. Switch the whole file, flush DNS, verify in the terminal. That is the whole method. 在此之前，分离的配置文件远胜于单一且充满注释的 hosts 文件。从三个文件开始：local 用于 .test 域名，staging 用于客户测试 IP，cutover 在迁移周之前保持为空。切换整个文件，刷新 DNS，在终端验证。这就是全部方法。

← 返回新闻列表 / Back to news list