本地搭建 HTTPS 测试环境

概览

• mkcert 是一个零配置的本地 CA 工具，可在你的系统信任存储里安装一个仅用于本地开发的根证书，然后为任意本地域名/IP生成受信任的证书。
• 适用于 macOS、Windows、Linux，并能为 Chrome/Edge/Safari 自动信任；Firefox需要额外的 NSS 支持。
• 证书仅用于开发环境，切勿用于生产。

一、安装

• macOS（Homebrew）
  • 安装 mkcert：brew install mkcert
  • 若要支持 Firefox：brew install nss
• Windows
  • Chocolatey：choco install mkcert
  • Scoop：scoop install mkcert
• Linux
  • Debian/Ubuntu：sudo apt install mkcert libnss3-tools
  • Arch：sudo pacman -S mkcert nss
  • Fedora：sudo dnf install mkcert nss
  • 如果发行版没有包，可从 mkcert Releases 下载二进制或用 Go 源码安装

二、初始化本地 CA

• 这一步会在系统信任存储安装一个仅用于开发的根证书

mkcert -install

• 查看 CA 存放目录（备份/管理用）：

mkcert -CAROOT

• 取消安装（清理）：

mkcert -uninstall

三、生成本地证书

• 为常见本地域名和 IP 生成证书（推荐包含 localhost、环回地址）

mkcert localhost 127.0.0.1 ::1

• 指定输出文件名（便于项目管理）

mkcert -cert-file local-cert.pem -key-file local-key.pem localhost 127.0.0.1 ::1

• 为自定义开发域名（例如 myapp.localhost 或 myapp.test）：
  • 建议使用保留域 .localhost 或 .test，或在 hosts 里映射到 127.0.0.1

mkcert myapp.localhost
# 或者
mkcert myapp.test

• 生成给 Java/Tomcat 等使用的 PKCS#12 格式：

mkcert -pkcs12 -p12-file local-dev.p12 localhost 127.0.0.1 ::1

• 生成客户端证书（若需要双向 TLS）：

mkcert -client dev-client

四、在常见服务器/框架中使用

• Nginx
  • ssl_certificate 指向证书文件；ssl_certificate_key 指向私钥文件

server {
  listen 443 ssl;
  server_name localhost;

  ssl_certificate     /path/to/local-cert.pem;
  ssl_certificate_key /path/to/local-key.pem;

  location / {
    proxy_pass http://127.0.0.1:3000;
  }
}

• Node.js（https 模块）

import fs from 'fs';
import https from 'https';
import express from 'express';

const app = express();
app.get('/', (req, res) => res.send('Hello HTTPS'));

const options = {
  key:  fs.readFileSync('local-key.pem'),
  cert: fs.readFileSync('local-cert.pem'),
};

https.createServer(options, app).listen(3443, () => {
  console.log('https://localhost:3443');
});

• Go（net/http）

package main

import (
  "fmt"
  "net/http"
)

func main() {
  http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintln(w, "Hello HTTPS")
  })
  // 使用 mkcert 生成的证书与私钥
  http.ListenAndServeTLS(":3443", "local-cert.pem", "local-key.pem", nil)
}

• Java（Tomcat 以 PKCS#12 为例）
  • server.xml 的 Connector：

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           SSLEnabled="true"
           keystoreFile="/path/to/local-dev.p12"
           keystoreType="PKCS12"
           keystorePass="changeit"
           scheme="https" secure="true" />

五、浏览器与信任注意事项

• Chrome/Edge/Safari：在 macOS/Windows/Linux 上一般会自动信任 mkcert 安装的本地 CA。
• Firefox：
  • 需安装 NSS（macOS: brew install nss；Linux: libnss3-tools）。
  • mkcert 会尝试向所有 Firefox profiles 导入 CA。如仍不信任，确认你当前 profile 是否被覆盖，或手动导入 CA（在 mkcert -CAROOT 找到 rootCA.pem）。
• 访问地址要与证书的 SAN 完全匹配：
  • 例如证书里有 localhost 和 127.0.0.1，那么访问 https://localhost 或 https://127.0.0.1 是有效的；访问自定义域名需在证书里包含该域名。
• 如果证书过期或变更：
  • 重新生成证书，重启服务器，必要时清除浏览器缓存与旧的证书记忆。

六、容器与反向代理

• Docker/Compose：
  • 推荐在宿主机生成证书，然后通过 volume 挂载到容器；容器内无需安装 mkcert。
• Traefik/Caddy/Nginx 等：
  • 将 mkcert 生成的证书/私钥指向对应配置项；确保主机名与证书 SAN 匹配。

七、移动设备与模拟器

• iOS 模拟器：继承 macOS 信任，一般可直接使用。
• 真机 iOS/Android：需把 mkcert 的根证书（rootCA.pem）手动安装到设备信任存储；安装后仍需确保域名解析到你的开发机（例如通过局域网 IP 或代理）。

八、常见问题排查

• 浏览器提示“不是私密连接”或 ERR_CERT_AUTHORITY_INVALID：
  • 确认已执行 mkcert -install。
  • 用正确的主机名/IP访问（与证书 SAN 一致）。
  • 重启浏览器或清除证书缓存。
• Firefox 仍不信任：
  • 安装 NSS 并再次运行 mkcert -install。
  • 检查是否在当前 profile 导入；必要时手动导入 rootCA。
• 证书不生效或文件找不到：
  • 检查路径与权限；确保服务器读取的是新生成的文件。
• 域名解析问题：
  • 使用 .localhost 或 .test，或在 hosts 文件中将自定义域名指向 127.0.0.1。

九、安全与清理

• 这些证书仅用于本地开发，不应部署到生产。
• 完成后可用 mkcert -uninstall 移除本地 CA。
• 不要将私钥与本地 CA 文件提交到版本控制系统。

快速上手命令总结

# 1) 安装（示例：macOS）
brew install mkcert && brew install nss

# 2) 安装本地 CA
mkcert -install

# 3) 生成证书与私钥
mkcert -cert-file local-cert.pem -key-file local-key.pem localhost 127.0.0.1 ::1

# 4) 在你的服务中引用上述文件并启用 HTTPS
# 5) 测试：https://localhost 或 https://127.0.0.1