本地快速启用 HTTPS

在本地浏览器里调试前端时，有时需要模拟真实的线上部署：页面使用指定域名，并通过 HTTPS 访问。直接使用 http://localhost:3000 或打开 HTML 文件，可能跑得通页面，却无法复现与域名、协议有关的行为。

比如下面这些场景：

• 第三方登录的回调地址已经配置成 https://xxx.com/callback。改用 localhost 后，协议、域名或端口与登记的地址不一致，登录流程会被拒绝。
• 登录态 Cookie 设置了 Domain=xxx.com 或 .xxx.com，还带有 Secure 属性。在 localhost 下无法按同样的域名规则使用这些 Cookie，普通 HTTP 也不满足它们的安全传输要求。
• 地图、支付等前端 SDK 配置了域名白名单，或服务端校验页面的 Origin。localhost 与线上域名不同，调试时可能直接触发校验失败。
• Service Worker、摄像头和麦克风等浏览器能力要求安全上下文。localhost 通常有开发例外，但换成普通 HTTP 自定义域名后，就不能依赖这个例外。

这时需要的是一个能快速打开的本地地址，例如 https://xxx.com：浏览器使用目标域名和 HTTPS，页面资源文件仍由本机提供。

快速启动#

下面以 macOS 和 Homebrew 为例，托管当前目录中的静态文件。先进入前端构建产物目录（例如 dist/）或存放 HTML 的目录，再执行命令。服务使用 Python 3.14 及以上版本。

xxx.com 是示例域名，实际使用时，把 hosts 记录、证书命令和访问地址中的域名一起替换。首次使用先完成准备；如果 /etc/hosts 已有这个域名的记录，应将它改为指向 127.0.0.1，避免重复配置。

# 首次准备：安装依赖、信任本地 CA，并将域名解析到本机
brew install mkcert python
mkcert -install
printf '\n127.0.0.1 xxx.com\n' | sudo tee -a /etc/hosts

然后执行这一组命令：

mkcert -cert-file /tmp/local-https-cert.pem \
  -key-file /tmp/local-https-key.pem \
  xxx.com

sudo "$(brew --prefix)/bin/python3" -m http.server 443 \
  --bind 127.0.0.1 \
  --directory "$PWD" \
  --tls-cert /tmp/local-https-cert.pem \
  --tls-key /tmp/local-https-key.pem

在浏览器中打开 https://xxx.com，就能访问当前目录的页面。终端保持运行，按 Ctrl+C 停止服务。后续使用同一个域名时，直接执行第二组命令即可。

基本思路#

浏览器访问 https://xxx.com 时，会解析域名、连接 HTTPS 默认端口 443，并检查服务端证书。把这些条件在本机补齐，就能用这个地址访问本地页面：

hosts 改变的是域名对应的连接地址。浏览器地址栏里的域名仍是 xxx.com，页面的 Origin 也仍是 https://xxx.com，因此可以按这个域名调试回调地址、Cookie 和 SDK 校验。

这种方式模拟的是本机浏览器看到的域名和 HTTPS 环境。页面请求其他域名的 API 时，跨域权限仍由 API 的 CORS 配置决定；hosts 也只影响本机解析，第三方服务器主动回调本机仍需要可达的网络入口。

验证与排查#

服务启动后，可以在另一个终端执行：

curl --verbose https://xxx.com/

正常情况下可以看到 TLS 证书验证成功、HTTP 200，以及页面的 HTML 内容。

如果想单独验证 HTTPS 服务，排除 hosts 配置或 DNS 缓存的影响，可以显式指定连接地址：

curl --verbose --resolve xxx.com:443:127.0.0.1 https://xxx.com/

--resolve 只影响这一次 curl 请求的解析结果，TLS 仍按 xxx.com 验证证书，也仍会使用这个域名发送请求。

如果浏览器仍然使用之前缓存的解析结果，可以刷新 macOS 的 DNS 缓存：

sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder

参考#

• mkcert 官方说明
• Python 3.14 http.server 文档