数得其道

道 · 法 · 术 · 器

⭐ 精选文章

mkcert 完全指南：本地 HTTPS 开发的终极解决方案

mkcertHTTPS本地开发SSL证书开发工具
mkcert 完全指南：本地 HTTPS 开发的终极解决方案

mkcert 完全指南：本地 HTTPS 开发的终极解决方案

为什么值得读这篇文章？

  • 本文适合： 前端开发者、全栈工程师、DevOps 工程师、需要本地 HTTPS 调试的技术人员
  • 如果你在问： “如何在本地开发环境使用 HTTPS？”、“怎样避免浏览器的安全警告？”、“本地如何测试 HTTP/2 或 WebSocket？“，这篇文章正是为你准备的
  • 解决痛点： 告别繁琐的 OpenSSL 配置，一键生成受信任的本地 HTTPS 证书

什么是 mkcert？

mkcert 是一个专为本地开发环境设计的 HTTPS 证书生成工具。它会自动在系统或浏览器中安装本地 CA（根证书），并用它来签发域名或 IP 对应的证书，让本地开发环境可以像生产环境一样使用 HTTPS。

核心优势

  • 零配置信任： 自动处理证书信任链，无需手动导入
  • 开发体验友好： 消除浏览器”不安全连接”警告
  • 多平台支持： 支持 macOS、Windows、Linux
  • 场景广泛： 适用于 HTTP/2、gRPC、WebSocket 等需要 TLS 的场景

安装 mkcert

macOS 安装

# 使用 Homebrew 安装
brew install mkcert

# 如果需要支持 Firefox
brew install nss

Windows 安装

# 使用 Chocolatey
choco install mkcert

# 或使用 Scoop
scoop install mkcert

Linux 安装

# Ubuntu/Debian
sudo apt install libnss3-tools
brew install mkcert

# 或直接下载可执行文件
# 访问 https://github.com/FiloSottile/mkcert/releases

基础使用指南

第一步：安装本地 CA

mkcert -install

这个命令会：

  • 生成并安装一个本地 CA（根证书）
  • 将证书存储到系统目录：
    • macOS: ~/Library/Application Support/mkcert
    • Windows: %LOCALAPPDATA%\mkcert
    • Linux: ~/.local/share/mkcert
  • 自动导入到系统和 Firefox 信任库

第二步：生成域名证书

# 为单个域名生成证书
mkcert example.com

# 为多个域名和 IP 生成证书
mkcert example.com www.example.com 127.0.0.1 ::1

# 生成通配符证书
mkcert "*.test" "*.localhost" localhost 127.0.0.1 ::1

生成的文件：

  • example.com.pem - SSL 证书
  • example.com-key.pem - 私钥文件

自定义输出文件名

mkcert -cert-file mycert.pem -key-file mykey.pem example.com

进阶技巧与配置

生成客户端证书（双向 TLS）

# 用于 mTLS 认证场景
mkcert -client client.example.com

查看 CA 信息

# 显示 CA 文件存储路径
mkcert -CAROOT

CA 目录包含：

  • rootCA.pem - 根证书
  • rootCA-key.pem - 根私钥

自定义证书有效期

# 生成 10 年有效期的证书
mkcert -days 3650 example.com

实战应用场景

与 Nginx 集成

server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate     /path/to/example.com.pem;
    ssl_certificate_key /path/to/example.com-key.pem;

    location / {
        root /var/www/html;
        index index.html;
    }
}

Node.js HTTPS 服务器

const fs = require("fs");
const https = require("https");

const options = {
  key: fs.readFileSync("./example.com-key.pem"),
  cert: fs.readFileSync("./example.com.pem"),
};

https
  .createServer(options, (req, res) => {
    res.writeHead(200, { "Content-Type": "text/html" });
    res.write("<h1>Hello HTTPS!</h1>");
    res.end();
  })
  .listen(443, () => {
    console.log("HTTPS Server running on https://example.com");
  });

Docker 容器中使用

# Dockerfile
FROM nginx:alpine
COPY example.com.pem /etc/ssl/certs/
COPY example.com-key.pem /etc/ssl/private/
COPY nginx.conf /etc/nginx/nginx.conf

常见问题解答

Q1: 浏览器仍然显示”不安全”？

解决步骤：

  1. 确认执行过 mkcert -install
  2. Firefox 用户需要安装 nss 包
  3. 重启浏览器
  4. 检查域名是否与证书匹配

Q2: 如何在移动设备上信任证书？

操作方法：

# 1. 找到 CA 证书位置
mkcert -CAROOT

# 2. 将 rootCA.pem 传输到移动设备
# 3. 在移动设备的设置中导入证书

Q3: 证书过期了怎么办？

# 重新生成证书
mkcert example.com

# 或指定更长有效期
mkcert -days 3650 example.com

Q4: 如何完全卸载 mkcert？

# 卸载本地 CA
mkcert -uninstall

# 删除生成的证书文件
rm *.pem

完整命令参考

命令功能说明
mkcert -install安装本地 CA
mkcert example.com为指定域名生成证书
mkcert a.com b.com 127.0.0.1为多个域名/IP 生成证书
mkcert -client name生成客户端证书
mkcert -cert-file c.pem -key-file k.pem name指定输出文件名
mkcert -CAROOT显示 CA 文件目录
mkcert -uninstall卸载本地 CA
mkcert -ecdsa example.com生成 ECDSA 类型证书
mkcert -days 365 example.com指定证书有效期

最佳实践建议

开发环境配置

  1. 统一域名规范： 使用 .local 或 .test 后缀
  2. 版本控制： 将证书文件加入 .gitignore
  3. 团队协作： 共享 CA 根证书给团队成员
  4. 自动化脚本： 编写脚本自动生成和配置证书

安全注意事项

  • 仅限开发环境： 不要在生产环境使用 mkcert
  • 私钥保护： 妥善保管生成的私钥文件
  • 定期更新： 定期重新生成证书避免过期

总结

mkcert 是本地 HTTPS 开发的利器，它极大简化了证书生成和信任配置的复杂度。通过本文的完整指南，你可以：

  • 快速搭建本地 HTTPS 环境
  • 解决浏览器安全警告问题
  • 支持 HTTP/2、WebSocket 等现代协议
  • 提升本地开发体验

无论是前端开发、API 调试，还是微服务测试，mkcert 都能让你的本地开发环境更接近生产环境，提高开发效率和代码质量。

立即开始： 安装 mkcert，让你的本地开发告别 HTTP，拥抱更安全的 HTTPS！