Ubuntu/Debian 系统下安装和使用 mkcert 的完整步骤

mkcert 是一款轻量级的本地 HTTPS 证书生成工具，无需手动配置 OpenSSL，可快速创建可信的本地开发证书。以下是 Ubuntu/Debian 系统下安装和使用 mkcert 的完整步骤：

一、前置依赖：安装 certutil

mkcert 依赖 certutil 管理系统根证书，先安装：

# Ubuntu/Debian
sudo apt update
sudo apt install -y libnss3-tools

注：libnss3-tools 包含 certutil，适配 Chrome/Firefox 等浏览器的证书信任机制。

二、安装 mkcert

方式 1：官方二进制包（推荐，适配所有系统）

# 下载最新版 mkcert（自动适配系统架构）
curl -JLO "https://dl.filippo.io/mkcert/latest?for=linux/amd64"
# 赋予执行权限
chmod +x mkcert-v*-linux-amd64
# 移动到系统可执行目录
sudo mv mkcert-v*-linux-amd64 /usr/local/bin/mkcert

方式 2：通过包管理器安装（仅部分新版系统支持）

# Ubuntu 22.04+/Debian 12+ 可直接用 apt
sudo apt install -y mkcert

方式 3：源码编译（备用）

# 安装 Go 环境（需 Go 1.19+）
sudo apt install -y golang-go
# 编译并安装
go install filippo.io/mkcert@latest
# 将 Go 编译产物加入 PATH
sudo ln -s ~/go/bin/mkcert /usr/local/bin/mkcert

三、验证安装

执行以下命令，输出版本号则安装成功：

mkcert --version

四、核心使用步骤

1. 安装本地根证书（关键：让系统信任 mkcert 生成的证书）

mkcert -install

效果：

  • 在 ~/.local/share/mkcert 生成根证书；

  • 自动将根证书添加到系统信任库（Linux 系统的 /etc/ssl/certs、浏览器的 NSS 数据库）；

  • 后续生成的证书都会基于此根证书，无需手动信任。

2. 生成本地 HTTPS 证书

示例 1：为单个域名生成证书
# 生成 localhost + 127.0.0.1 的证书（默认保存为 localhost.pem 和 localhost-key.pem）
mkcert localhost 127.0.0.1 ::1
示例 2：为自定义域名生成证书
# 生成 example.test 及子域名的证书
mkcert example.test "*.example.test" localhost 127.0.0.1 ::1
示例 3：指定证书输出路径/名称
# 生成证书并指定文件名（key 为私钥，crt 为证书）
mkcert -key-file my-key.pem -cert-file my-cert.pem localhost

3. 查看已安装的根证书

mkcert -CAROOT
# 输出：/home/[你的用户名]/.local/share/mkcert

4. 卸载根证书（清理环境）

mkcert -uninstall

五、常见使用场景

1. 配合 Nginx 使用

将生成的证书配置到 Nginx 配置文件（如 nginx.conf）：

server {
    listen 443 ssl;
    server_name localhost;

    # 指向 mkcert 生成的证书文件
    ssl_certificate /path/to/localhost.pem;
    ssl_certificate_key /path/to/localhost-key.pem;

    # 其他 SSL 配置（可选）
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
}

2. 配合 Node.js/Express 使用

const https = require('https');
const fs = require('fs');
const express = require('express');
const app = express();

// 加载 mkcert 生成的证书
const options = {
  key: fs.readFileSync('./localhost-key.pem'),
  cert: fs.readFileSync('./localhost.pem')
};

// 启动 HTTPS 服务
https.createServer(options, app).listen(3000, () => {
  console.log('HTTPS 服务运行在 https://localhost:3000');
});

3. 配合vite.config.js（Vue CLI 生产配置）

适用于 Vue 3 + Vite 项目，覆盖 HTTPS 适配、打包优化、部署兼容等生产核心场景：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import path from 'path'
import { visualizer } from 'rollup-plugin-visualizer' // 可选：打包体积分析
import compressPlugin from 'vite-plugin-compression' // 可选：Gzip 压缩

// 区分环境：生产环境变量（可通过 .env.production 配置）
const isProduction = process.env.NODE_ENV === 'production'

export default defineConfig({
  // 1. 基础路径（适配 Nginx/Apache 部署路径，如域名根目录则为 '/'，子目录则为 '/vue-app/'）
  base: isProduction ? '/' : '/',

  // 2. 插件配置（生产环境优化）
  plugins: [
    vue(),
    // 可选：打包体积分析（执行 npm run build 后生成 stats.html）
    isProduction && visualizer({ open: false, filename: 'stats.html' }),
    // 可选：Gzip 压缩（配合 Nginx gzip_static on 提升加载速度）
    isProduction && compressPlugin({
      ext: '.gz',
      algorithm: 'gzip',
      threshold: 10240, // 大于 10kb 的文件才压缩
      deleteOriginFile: false // 不删除原文件
    })
  ].filter(Boolean), // 过滤空值

  // 3. 生产环境构建优化
  build: {
    // 输出目录（默认 dist，可适配服务器路径）
    outDir: 'dist',
    // 静态资源目录
    assetsDir: 'static',
    // 清除控制台日志（生产环境禁用 console.log）
    minify: 'terser',
    terserOptions: {
      compress: {
        drop_console: true,
        drop_debugger: true
      }
    },
    // 拆分代码：第三方依赖单独打包（如 vue、axios）
    rollupOptions: {
      output: {
        chunkFileNames: 'static/js/[name]-[hash].js',
        entryFileNames: 'static/js/[name]-[hash].js',
        assetFileNames: 'static/[ext]/[name]-[hash].[ext]',
        // 手动拆分依赖（可选）
        manualChunks: {
          vue: ['vue', 'vue-router', 'pinia'],
          utils: ['axios', 'lodash']
        }
      }
    },
    // 开启 sourcemap（生产环境可选，调试用，上线前关闭）
    sourcemap: false,
    // 最大打包体积警告阈值（默认 500kb）
    chunkSizeWarningLimit: 1000
  },

  // 4. 服务器配置（生产环境无需配置 devServer，仅本地开发用）
  server: {
    // 本地开发 HTTPS 配置（生产环境由 Nginx 接管，此处仅开发用）
    https: isProduction 
      ? false // 生产环境禁用 Vite 内置 HTTPS，由 Web 服务器配置
      : {
          key: path.resolve(__dirname, './ssl/key.pem'), // mkcert 生成的私钥
          cert: path.resolve(__dirname, './ssl/cert.pem') // mkcert 生成的证书
        },
    // 生产环境无需代理，代理逻辑移至 Nginx
    proxy: isProduction ? {} : {
      '/api': {
        target: 'https://prod-api.example.com',
        changeOrigin: true,
        secure: true // 生产环境接口需验证 SSL 证书（开发环境可设为 false）
      }
    }
  },

  // 5. 别名配置（适配生产环境路径）
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src')
    }
  }
})

4. 配合vue.config.js（Vite 生产配置）

适用于 Vue 2/Vue 3 + Vue CLI（@vue/cli）项目，核心适配生产环境 HTTPS、打包优化、部署兼容：

const path = require('path')
const CompressionPlugin = require('compression-webpack-plugin') // Gzip 压缩
const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer') // 体积分析

const isProduction = process.env.NODE_ENV === 'production'

module.exports = {
  // 1. 基础路径（同 Vite，适配部署子目录）
  publicPath: isProduction ? '/' : '/',

  // 2. 输出目录
  outputDir: 'dist',

  // 3. 静态资源目录
  assetsDir: 'static',

  // 4. 生产环境禁用 sourcemap
  productionSourceMap: false,

  // 5. webpack 配置（生产环境优化）
  configureWebpack: {
    // 别名配置
    resolve: {
      alias: {
        '@': path.resolve(__dirname, 'src')
      }
    },
    // 生产环境插件
    plugins: [
      // Gzip 压缩
      new CompressionPlugin({
        algorithm: 'gzip',
        test: /\.(js|css|html|svg)$/,
        threshold: 10240,
        minRatio: 0.8
      }),
      // 可选：打包体积分析（执行 npm run build --report 生成）
      ...(isProduction ? [new BundleAnalyzerPlugin({ openAnalyzer: false })] : [])
    ],
    // 拆分第三方依赖
    optimization: {
      splitChunks: {
        chunks: 'all',
        cacheGroups: {
          vendor: {
            name: 'chunk-vendors',
            test: /[\\/]node_modules[\\/]/,
            priority: 10,
            chunks: 'initial'
          },
          common: {
            name: 'chunk-common',
            minChunks: 2,
            priority: 5,
            chunks: 'initial',
            reuseExistingChunk: true
          }
        }
      }
    }
  },

  // 6. 链式 webpack 配置（更细粒度控制）
  chainWebpack: config => {
    // 生产环境清除 console
    if (isProduction) {
      config.optimization.minimizer('terser').tap(args => {
        args[0].terserOptions.compress.drop_console = true
        args[0].terserOptions.compress.drop_debugger = true
        return args
      })
    }

    // 图片压缩（生产环境）
    config.module
      .rule('images')
      .use('image-webpack-loader')
      .loader('image-webpack-loader')
      .options({
        mozjpeg: { quality: 80, progressive: true },
        optipng: { enabled: false },
        pngquant: { quality: [0.6, 0.8] },
        gifsicle: { interlaced: false }
      })
      .end()
  },

  // 7. devServer（仅本地开发用，生产环境由 Nginx 接管）
  devServer: {
    // 本地开发 HTTPS 配置（生产环境禁用）
    https: !isProduction && {
      key: path.resolve(__dirname, './ssl/key.pem'),
      cert: path.resolve(__dirname, './ssl/cert.pem')
    },
    // 生产环境无需代理，代理移至 Nginx
    proxy: isProduction ? {} : {
      '/api': {
        target: 'https://prod-api.example.com',
        changeOrigin: true,
        secure: true // 生产接口验证 SSL 证书
      }
    },
    // 禁用生产环境 devServer 功能
    open: !isProduction,
    hot: !isProduction
  }
}

六、常见问题解决

1. 执行 mkcert -install 提示权限不足

# 用 sudo 重新执行（需确保环境变量正确）
sudo mkcert -install

2. 浏览器提示证书不受信任

  • 确认已执行 mkcert -install；

  • 重启浏览器（尤其是 Firefox，需手动刷新证书库）；

  • 手动导入根证书：

    • # 找到根证书路径 CAROOT=$(mkcert -CAROOT) # 手动添加到系统信任 sudo cp "$CAROOT/rootCA.pem" /usr/local/share/ca-certificates/rootCA.crt sudo update-ca-certificates

3. 下载 mkcert 速度慢（国内网络）

替换为国内镜像（临时）：

# 手动下载（以 amd64 为例）
wget https://mirror.ghproxy.com/https://github.com/FiloSottile/mkcert/releases/download/v1.4.4/mkcert-v1.4.4-linux-amd64
chmod +x mkcert-v1.4.4-linux-amd64
sudo mv mkcert-v1.4.4-linux-amd64 /usr/local/bin/mkcert

4. 卸载 mkcert

# 删除二进制文件
sudo rm /usr/local/bin/mkcert
# 卸载根证书
mkcert -uninstall
# 删除根证书目录
rm -rf $(mkcert -CAROOT)

七、关键说明

  1. mkcert 生成的证书仅用于本地开发，不可用于生产环境；

  2. 根证书仅保存在本地，不会上传到任何服务器，安全性可控；

  3. 支持多域名、通配符域名（如 *.test），适配大部分开发场景。

以上步骤适配 Ubuntu 18.04/20.04/22.04 及 Debian 10/11/12，是 mkcert 官方推荐的标准用法，可快速实现本地 HTTPS 开发环境。

CentOS系统下mkcert的安装、使用、常见问题解决及卸载指南

CentOS（包括 CentOS 7/8/9 Stream）系统下安装和使用 mkcert 需适配其包管理机制（YUM/DNF）和依赖环境，以下是完整且适配不同 CentOS 版本的步骤，兼顾稳定性和易用性：

一、前置准备：安装依赖

mkcert 依赖 certutil 管理系统/浏览器根证书，CentOS 需安装对应依赖包：

1. CentOS 7

2. CentOS 8/9 Stream

sudo dnf update -y
# CentOS 8/9 用 dnf 安装 nss-tools
sudo dnf install -y nss-tools
# 补充依赖（可选）
sudo dnf install -y gcc openssl-devel

注：nss-tools 包含 certutil，是 Chrome/Firefox 等浏览器信任证书的核心依赖。

二、安装 mkcert（3种方式，任选其一）

方式 1：官方二进制包（推荐，适配所有 CentOS 版本）

无需编译，直接下载适配架构的二进制文件，是最通用的方式：

# 下载最新版 mkcert（自动适配 linux/amd64 架构）
curl -JLO "https://dl.filippo.io/mkcert/latest?for=linux/amd64"
# 赋予执行权限
chmod +x mkcert-v*-linux-amd64
# 移动到系统可执行目录（全局可用）
sudo mv mkcert-v*-linux-amd64 /usr/local/bin/mkcert

方式 2：通过 EPEL 源安装（仅 CentOS 8/9 推荐）

CentOS 8/9 的 EPEL 源已收录 mkcert，可直接通过包管理器安装：

# 安装 EPEL 源（若未安装）
sudo dnf install -y epel-release
# 安装 mkcert
sudo dnf install -y mkcert

方式 3：源码编译（备用，适配所有版本）

若二进制包下载失败，可通过 Go 编译安装：

# 安装 Go 环境（CentOS 7 需手动安装高版本 Go，CentOS 8/9 可直接 dnf 安装）
## CentOS 7 安装 Go
wget https://dl.google.com/go/go1.21.0.linux-amd64.tar.gz
sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.21.0.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

## CentOS 8/9 安装 Go
# sudo dnf install -y golang

# 编译并安装 mkcert
go install filippo.io/mkcert@latest
# 软链接到系统目录（全局可用）
sudo ln -s ~/go/bin/mkcert /usr/local/bin/mkcert

如果安装出错

CentOS 8 镜像源修复及 nss-tools 安装指南

问题是 CentOS 8 官方镜像源已停止维护，导致 mirrorlist.centos.org 无法解析，进而 yum 安装包失败。以下是针对性的解决步骤，先修复镜像源，再安装 nss-tools：

一、核心原因

CentOS 8 于 2022 年 12 月停止官方支持，原镜像源（mirrorlist.centos.org）已下线，需切换到 CentOS Vault 归档源 或第三方镜像源（如阿里云）。

二、修复步骤（CentOS 8 适配）

1. 备份原有 yum 配置文件（防止出错）

sudo mkdir -p /etc/yum.repos.d/bak
sudo mv /etc/yum.repos.d/CentOS-* /etc/yum.repos.d/bak/

2. 替换为阿里云 CentOS 8 Vault 源

# 下载阿里云 CentOS 8 归档源配置
sudo curl -o /etc/yum.repos.d/CentOS-Base.repo https://mirrors.aliyun.com/repo/Centos-vault-8.5.2111.repo

3. 清理并重建 yum 缓存

sudo yum clean all
sudo yum makecache

4. 重新安装 nss-tools

sudo yum install -y nss-tools

三、若仍报错（DNS 解析问题）

如果执行后仍提示「Could not resolve host」，说明服务器 DNS 配置异常，需先修复 DNS：

# 临时修改 DNS（阿里云公共 DNS）
echo "nameserver 223.5.5.5" | sudo tee /etc/resolv.conf
echo "nameserver 223.6.6.6" | sudo tee -a /etc/resolv.conf

# 重启网络服务（CentOS 8）
sudo systemctl restart NetworkManager

修改后再次执行 yum makecache 和 yum install -y nss-tools。

四、验证安装

# 检查 certutil 是否安装成功（nss-tools 核心工具）
certutil --version

输出类似 certutil: 3.67.0 则表示依赖安装成功。

五、后续安装 mkcert 建议

修复源后，继续按之前的步骤安装 mkcert（优先选择官方二进制包，避免编译问题）：

# 下载 mkcert 二进制包（国内镜像加速）
wget https://mirror.ghproxy.com/https://github.com/FiloSottile/mkcert/releases/download/v1.4.4/mkcert-v1.4.4-linux-amd64
chmod +x mkcert-v1.4.4-linux-amd64
sudo mv mkcert-v1.4.4-linux-amd64 /usr/local/bin/mkcert

# 验证 mkcert
mkcert --version

六、补充：CentOS 8 Stream 适配（若为 Stream 版本）

如果你的系统是 CentOS 8 Stream（而非传统 CentOS 8），需切换到 Stream 专属源：

sudo curl -o /etc/yum.repos.d/CentOS-Stream-Base.repo https://mirrors.aliyun.com/repo/Centos-stream-8.repo
sudo yum clean all && sudo yum makecache

关键说明

  1. CentOS 8 停止维护后，所有 yum 操作都需依赖 Vault 归档源，上述阿里云源是国内最稳定的选择；

  2. 若后续安装其他包（如 gcc、openssl-devel），同样需先执行上述源修复步骤；

  3. 建议长期使用的话，可升级到 CentOS 9 Stream（仍在维护）或迁移到 Rocky Linux/AlmaLinux（CentOS 替代版）。

按此步骤操作后，即可正常安装 nss-tools 及其他依赖包。

三、验证安装

执行以下命令，输出版本号则安装成功：

mkcert --version

四、核心使用步骤

1. 安装本地根证书（关键：让系统信任 mkcert 证书）

mkcert -install

效果：

  • 根证书生成在 ~/.local/share/mkcert 目录；

  • 自动将根证书添加到：

    • 系统级信任库（/etc/pki/ca-trust/source/anchors/）；

    • NSS 数据库（适配 Chrome/Firefox 浏览器）；

  • 后续生成的证书均基于此根证书，无需手动信任。

2. 生成本地 HTTPS 证书

示例 1：基础用法（localhost + 本地 IP）
# 生成 localhost、127.0.0.1、IPv6 本地地址的证书
mkcert localhost 127.0.0.1 ::1
# 生成的文件：localhost.pem（证书）、localhost-key.pem（私钥）
示例 2：自定义域名/通配符证书
# 生成 example.test 及所有子域名的证书
mkcert example.test "*.example.test" localhost 127.0.0.1
示例 3：指定证书输出路径/名称
# 自定义证书文件名和路径
mkcert -key-file /opt/ssl/my-key.pem -cert-file /opt/ssl/my-cert.pem localhost

3. 查看根证书目录

mkcert -CAROOT
# 输出：/home/[你的用户名]/.local/share/mkcert

4. 卸载根证书（清理环境）

mkcert -uninstall

五、常见使用场景

1. 配合 Nginx 使用

编辑 Nginx 配置文件（如 /etc/nginx/conf.d/https.conf）：

server {
    listen 443 ssl;
    server_name localhost;

    # 指向 mkcert 生成的证书
    ssl_certificate /path/to/localhost.pem;
    ssl_certificate_key /path/to/localhost-key.pem;

    # 优化 SSL 配置（可选）
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:1m;
}

重启 Nginx 生效：

sudo systemctl restart nginx

2. 配合 Node.js/Express 使用

const https = require('https');
const fs = require('fs');
const express = require('express');
const app = express();

// 加载证书
const options = {
  key: fs.readFileSync('./localhost-key.pem'),
  cert: fs.readFileSync('./localhost.pem')
};

// 启动 HTTPS 服务
https.createServer(options, app).listen(3000, () => {
  console.log('HTTPS 服务运行在 https://localhost:3000');
});

六、常见问题解决

1. 执行 mkcert 提示「command not found」

  • 原因：二进制文件未在 PATH 目录，或软链接失效；

  • 解决：

    • # 检查文件是否存在 ls /usr/local/bin/mkcert # 若不存在，重新移动/软链接 sudo mv /path/to/mkcert-v*-linux-amd64 /usr/local/bin/mkcert # 刷新 PATH source ~/.bashrc

2. 浏览器提示证书不受信任

  • 原因 1：根证书未正确安装 → 重新执行 mkcert -install；

  • 原因 2：Firefox 不使用系统根证书库 → 手动导入：

    • 执行 mkcert -CAROOT 找到 rootCA.pem；

    • 打开 Firefox → 设置 → 隐私与安全 → 证书 → 查看证书 → 权威 → 导入；

    • 选择 rootCA.pem，勾选「信任此 CA 标识网站」。

3. mkcert -install 提示权限不足

  • 解决：以 root 权限执行（CentOS 7/8/9 通用）：

    • sudo mkcert -install

4. 下载二进制包速度慢（国内网络）

替换为 GitHub 镜像下载：

# 以 amd64 架构为例
wget https://mirror.ghproxy.com/https://github.com/FiloSottile/mkcert/releases/download/v1.4.4/mkcert-v1.4.4-linux-amd64
chmod +x mkcert-v1.4.4-linux-amd64
sudo mv mkcert-v1.4.4-linux-amd64 /usr/local/bin/mkcert

5. CentOS 7 编译 Go 失败

  • 原因：CentOS 7 自带 Go 版本过低；

  • 解决：手动安装高版本 Go（参考方式 3 中的 CentOS 7 Go 安装步骤）。

七、卸载 mkcert

# 1. 删除二进制文件
sudo rm -f /usr/local/bin/mkcert
# 2. 卸载根证书
mkcert -uninstall
# 3. 删除根证书目录
rm -rf $(mkcert -CAROOT)
# 4. 若为源码安装，删除 Go 编译产物
rm -rf ~/go/bin/mkcert

八、关键说明

  1. CentOS 7 需注意：yum 源部分包版本较低，优先选择「官方二进制包」安装 mkcert，避免编译问题；

  2. mkcert 生成的证书仅用于本地开发/测试，严禁用于生产环境；

  3. 若使用 Docker 部署服务，需将 mkcert 生成的证书挂载到容器内，并确保容器内应用加载证书路径正确。

以上步骤适配 CentOS 7（维护中）、CentOS 8 Stream、CentOS 9 Stream 所有主流版本，是经过验证的标准流程，可快速搭建本地 HTTPS 开发环境。

Windows 系统下 mkcert 的安装、使用、常见问题解决及关键说明

Windows 系统下安装和使用 mkcert 分为 传统手动安装 和 包管理器安装（推荐，更便捷），以下是完整步骤，适配 Windows 10/11 所有版本：

一、前置准备

mkcert 依赖系统根证书信任机制，Windows 无需额外安装 certutil（系统自带），仅需确保：

  • 以 管理员权限 运行终端（PowerShell/CMD）（部分步骤需要）；

  • 若使用 Chocolatey/Scoop 包管理器，提前安装（可选，推荐）。

二、安装方式（任选其一）

方式 1：Chocolatey 安装（推荐，自动配置）

Chocolatey 是 Windows 主流包管理器，一键安装无需手动配置：

  1. 安装 Chocolatey（若未安装）：

  1. 以管理员身份打开 PowerShell，执行：

    Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

  1. 安装 mkcert：

    1. choco install mkcert -y

方式 2：Scoop 安装（轻量包管理器）

Scoop 适合开发者，无管理员权限也可安装：

  1. 安装 Scoop（若未安装）：

  1. 打开普通 PowerShell，执行：

    Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
irm get.scoop.sh | iex

  1. 安装 mkcert：

    1. scoop install mkcert

方式 3：手动下载二进制包（适配所有场景）

若不想用包管理器，手动下载可执行文件：

  1. 访问 mkcert 官方下载页，下载 Windows 版本（如 mkcert-v1.4.4-windows-amd64.exe）；

  2. 将文件重命名为 mkcert.exe，放到自定义目录（如 C:\Tools\mkcert）；

  3. 将该目录添加到 系统环境变量 PATH（确保任意终端可执行 mkcert）：

    1. 右键「此电脑」→「属性」→「高级系统设置」→「环境变量」；

    2. 在「系统变量」的 Path 中添加 C:\Tools\mkcert；

    3. 重启终端生效。

三、验证安装

打开 PowerShell/CMD（任意权限），执行：

mkcert --version

输出版本号（如 v1.4.4）则安装成功。

四、核心使用步骤

1. 安装本地根证书（关键）

以管理员身份打开 PowerShell，执行：

mkcert -install

效果：

  • 自动在 %USERPROFILE%.local\share\mkcert 生成根证书；

  • 将根证书添加到 Windows 「受信任的根证书颁发机构」（系统级别信任）；

  • 自动适配 Chrome/Edge/Firefox 等浏览器的证书信任（Firefox 需额外确认）。

2. 生成本地 HTTPS 证书

示例 1：生成 localhost 证书（最常用）
# 生成 localhost + 127.0.0.1 + ::1 的证书，保存为 localhost.pem 和 localhost-key.pem
mkcert localhost 127.0.0.1 ::1
示例 2：自定义域名/通配符证书
# 生成 example.test 及子域名证书
mkcert example.test "*.example.test" localhost 127.0.0.1
示例 3：指定证书输出路径/名称
# 生成证书并自定义文件名
mkcert -key-file my-key.pem -cert-file my-cert.pem localhost

3. 查看根证书目录

mkcert -CAROOT
# 输出：C:\Users\[你的用户名]\.local\share\mkcert

4. 卸载根证书（清理环境）

以管理员身份执行：

mkcert -uninstall

五、常见使用场景

1. 配合 Nginx for Windows 使用

将生成的证书配置到 Nginx 配置文件（nginx.conf）：

server {
    listen 443 ssl;
    server_name localhost;

    # 证书路径（注意 Windows 路径分隔符用 / 或 \\）
    ssl_certificate C:/nginx/conf/localhost.pem;
    ssl_certificate_key C:/nginx/conf/localhost-key.pem;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
}

2. 配合 Node.js/Express 使用

const https = require('https');
const fs = require('fs');
const express = require('express');
const app = express();

// 加载证书（路径适配 Windows）
const options = {
  key: fs.readFileSync('./localhost-key.pem'),
  cert: fs.readFileSync('./localhost.pem')
};

// 启动 HTTPS 服务
https.createServer(options, app).listen(3000, () => {
  console.log('HTTPS 服务运行在 https://localhost:3000');
});

六、常见问题解决

1. 执行 mkcert 提示「不是内部或外部命令」

  • 原因：环境变量未配置或未重启终端；

  • 解决：

    • 确认 mkcert.exe 所在目录已加入系统 PATH；

    • 重启终端（或注销重新登录）；

    • 手动指定路径执行（如 C:\Tools\mkcert\mkcert.exe --version）。

2. 浏览器（如 Firefox）提示证书不受信任

  • Firefox 不使用系统根证书库，需手动导入：

    • 执行 mkcert -CAROOT 找到根证书路径（如 rootCA.pem）；

    • 打开 Firefox → 设置 → 隐私与安全 → 证书 → 查看证书 → 权威 → 导入；

    • 选择 rootCA.pem，勾选「信任此 CA 标识网站」。

3. mkcert -install 提示权限不足

  • 原因：未以管理员身份运行终端；

  • 解决：右键 PowerShell →「以管理员身份运行」，再执行安装命令。

4. 下载二进制包速度慢（国内网络）

替换为 GitHub 镜像下载：

# 以 v1.4.4 为例，适配 amd64 架构
irm https://mirror.ghproxy.com/https://github.com/FiloSottile/mkcert/releases/download/v1.4.4/mkcert-v1.4.4-windows-amd64.exe -OutFile mkcert.exe
# 移动到系统目录（如 C:\Windows\System32，无需配置 PATH）
Move-Item .\mkcert.exe C:\Windows\System32\

5. 卸载 mkcert

  • 包管理器安装的卸载：

    • # Chocolatey choco uninstall mkcert -y # Scoop scoop uninstall mkcert

  • 手动安装的卸载：

    • 删除 mkcert.exe 文件；

    • 执行 mkcert -uninstall 卸载根证书；

    • 删除根证书目录：rm -r $env:USERPROFILE.local\share\mkcert（PowerShell）。

七、关键说明

  1. mkcert 生成的证书仅用于本地开发，不可用于生产环境；

  2. Windows 下根证书存储在「用户级 + 系统级」，卸载后需重启浏览器生效；

  3. 若使用 WSL2（Windows 子系统），需在 WSL2 内单独安装 mkcert（参考 Ubuntu/Debian 安装步骤），WSL2 与 Windows 证书库不互通。

以上步骤覆盖 Windows 主流安装方式，包管理器安装是最优选择，无需手动配置环境变量，适合大部分开发者。