1. 项目概述为什么要在WSL里折腾mkcert如果你是一个在Windows上使用WSLWindows Subsystem for Linux进行Web开发的开发者那么“本地HTTPS”这个问题你肯定遇到过。无论是开发前端项目需要调用浏览器的某些高级API还是调试后端服务需要模拟真实的HTTPS环境一个有效的、被浏览器信任的SSL/TLS证书都是刚需。但每次去申请一个免费的公共证书或者自己用OpenSSL生成一个然后手动导入浏览器信任过程都相当繁琐。这就是mkcert这个工具闪亮登场的地方。它被设计用来解决一个核心痛点一键生成在本地开发环境中被浏览器和操作系统信任的证书。它的原理很简单就是在你的机器上安装一个本地的私有根证书颁发机构CA然后用这个CA去签发针对你本地域名比如localhost127.0.0.1myapp.test的证书。因为浏览器信任了你安装的根证书所以由它签发的所有子证书都会被自动信任不再有烦人的“不安全连接”警告。那么为什么要把mkcert部署在WSL环境里呢这背后有几个非常实际的考量。首先很多现代开发工具链和服务器比如Node.js的某些开发服务器、Go语言生态的工具本身就运行在WSL的Linux环境中在WSL内生成和使用证书路径和权限管理更自然与你的开发流程集成度更高。其次WSL2采用了虚拟化技术拥有独立的虚拟网络接口其IP地址通常是172.x.x.x与Windows主机的localhost并不完全等同。直接在WSL里为这个内部IP生成证书可以确保服务在WSL内部被访问时也是HTTPS的。最后这也是一种“环境隔离”的思路让开发依赖尽可能存在于WSL中保持Windows主机的相对干净。所以这个项目的目标非常明确在WSL的Linux环境中安装并运行mkcert生成用于本地开发的证书并将mkcert创建的根证书安装到Windows系统中最终实现在Windows的浏览器里无警告访问WSL中运行的HTTPS网站。整个过程涉及Linux环境配置、证书工具使用和Windows系统级信任操作是一个典型的跨系统开发生态搭建案例。2. 核心需求与前置准备解析在开始动手之前我们需要把整个流程拆解清楚并准备好必要的环境。这个项目不是简单的命令执行它连接了WSL和Windows两个系统任何一个环节的疏漏都可能导致最终失败。2.1 明确技术栈与依赖关系整个流程依赖于几个关键组件它们环环相扣WSL 2 环境这是我们的主战场。WSL 1由于网络架构不同在本地回环地址localhost的代理和访问上可能会有更多坑强烈建议使用WSL 2。你需要一个Linux发行版如Ubuntu、Debian等。mkcert工具核心工具用于创建本地CA和签发证书。它是一个用Go编写的单文件二进制程序不需要复杂的运行时环境。Windows 证书存储最终需要将mkcert生成的根证书一个.pem或.crt文件导入到Windows的“受信任的根证书颁发机构”存储中。这需要管理员权限。Web 服务器用于测试的Web服务器例如Nginx、Apache或者Node.js的http-server、serve亦或是像vite、webpack-dev-server这样的开发服务器。它们需要被配置为使用我们生成的证书文件。2.2 环境检查与准备工作在WSL终端中请依次执行以下检查确保基础环境就绪1. 确认WSL版本与网络打开Windows终端或PowerShell输入wsl --status。查看输出确认你使用的是WSL 2。同时在WSL内部运行ip addr show命令找到eth0接口记下它的IP地址通常是172.xx.xx.xx。这个地址是WSL虚拟机的内部IP我们后续可能会用到。2. 更新系统并安装基础工具在WSL终端中首先更新软件包列表并安装一些可能需要的工具比如curl和wget用于下载mkcert以及ca-certificates更新系统的CA证书包虽然不是必须但能避免一些潜在问题。sudo apt update sudo apt upgrade -y sudo apt install -y curl wget ca-certificates3. 规划证书存储路径这是一个容易被忽略但很重要的细节。mkcert默认会将生成的根证书和密钥放在$(mkcert -CAROOT)指示的目录通常是~/.local/share/mkcert或~/.mkcert。我们生成的网站证书也需要一个固定的地方存放。建议在用户目录下创建一个专用文件夹例如~/certs这样管理起来更清晰。mkdir -p ~/certs这个~/certs目录将是我们后续所有证书操作的工作区。注意权限问题。确保你对自己的家目录和~/certs有读写权限。mkcert在安装根证书时需要向系统证书存储写入文件这需要sudo权限。而生成网站证书通常在当前用户目录下即可。3. 在WSL中部署与配置mkcert环境准备好后我们就可以开始核心步骤了。这一步的目标是在WSL中成功安装mkcert并初始化本地CA。3.1 安装mkcert的几种方式及选择mkcert官方提供了多种安装方式选择哪种取决于你的网络环境和个人偏好。方式一使用Linux发行版的包管理器推荐如果可用这是最干净的方式。例如在Ubuntu/Debian上你可以通过系统维护的仓库安装。但请注意仓库中的版本可能不是最新的。sudo apt install -y mkcert安装完成后直接运行mkcert --version检查是否成功。方式二使用预编译的二进制文件通用方法这是最直接、能确保获取最新版的方法。我们使用curl从GitHub Releases下载。# 下载最新版的Linux二进制文件 curl -JLO https://github.com/FiloSottile/mkcert/releases/latest/download/mkcert-linux-amd64 # 下载完成后文件名为 mkcert-linux-amd64 # 将其重命名为 mkcert并移动到可执行路径 mv mkcert-linux-amd64 mkcert chmod x mkcert # 将 mkcert 移动到系统路径方便全局调用 sudo mv mkcert /usr/local/bin/再次运行mkcert --version确认。方式三通过Go工具安装如果你的WSL里已经安装了Go语言环境go version那么可以用这种方式go install filippo.io/mkcertlatest安装后二进制文件会在$GOPATH/bin或$HOME/go/bin下请确保该路径在你的$PATH环境变量中。实操心得我个人强烈推荐方式二。原因有三第一它不依赖系统仓库的更新节奏总能拿到最新版第二它不污染系统包管理器卸载时直接删除/usr/local/bin/mkcert文件即可第三过程透明下载的就是一个静态链接的二进制文件没有复杂的依赖。方式一虽然简单但遇到过旧版本在某些新系统上兼容性问题。方式三则引入了对Go环境的依赖不够纯粹。3.2 初始化本地证书颁发机构CA安装好mkcert后第一步不是直接生成网站证书而是初始化本地的CA。这个CA就是后续所有证书的“信任根源”。执行以下命令mkcert -install这个命令会做几件事在$(mkcert -CAROOT)目录下生成一对密钥文件根证书rootCA.pem和私钥rootCA-key.pem。尝试将根证书rootCA.pem安装到**当前系统即WSL的Linux系统**的信任存储中。对于基于Debian/Ubuntu的系统它会将证书复制到/usr/local/share/ca-certificates/目录然后调用update-ca-certificates命令让系统信任它。你可以通过以下命令验证CA是否创建成功以及其位置# 查看CA根证书存放目录 mkcert -CAROOT # 列出该目录下的文件 ls -la $(mkcert -CAROOT)你应该能看到rootCA.pem和rootCA-key.pem这两个文件。请务必妥善保管rootCA-key.pem它是你整个本地证书体系的“命门”一旦泄露任何人用它签发的证书都会被你的系统信任。重要提示mkcert -install在WSL中安装的根证书只对WSL内部的Linux环境生效。这意味着在WSL内部使用curl或wget访问一个由该CA签发的HTTPS网站时不会报证书错误。但是Windows系统及其上的浏览器如Chrome、Edge此时还完全不认识这个CA。这就是为什么我们后续必须把rootCA.pem文件手动导入Windows。3.3 为本地域名生成SSL证书现在我们可以用这个本地CA为我们需要的域名签发证书了。假设我们要为localhost和127.0.0.1以及WSL的内部IP172.25.123.456请替换为你自己的生成证书。切换到我们之前创建的证书目录然后执行生成命令cd ~/certs mkcert localhost 127.0.0.1 172.25.123.456命令执行后你会看到类似输出Created a new certificate valid for the following names - localhost - 127.0.0.1 - 172.25.123.456 The certificate is at ./localhost2.pem and the key at ./localhost2-key.pem ✅它生成了两个文件localhost2.pem这就是证书文件包含公钥。localhost2-key.pem这是对应的私钥文件。文件名解析mkcert默认以第一个域名这里是localhost为基础命名文件后面的2表示还有另外两个主题备用名称SAN。你也可以用-cert-file和-key-file参数来自定义输出文件名这对于管理多个项目的证书非常有用。mkcert -cert-file myapp.pem -key-file myapp-key.pem myapp.local 192.168.1.100注意事项生成的私钥文件*-key.pem是未加密的这意味着任何能访问到这个文件的人都可以使用它。在开发环境中这通常可以接受但切勿将其提交到版本控制系统如Git中。一个好的做法是在项目根目录的.gitignore文件中添加*.pem或*.key来忽略所有证书和密钥文件。4. 将根证书安装到Windows系统这是实现“在Windows浏览器中无警告访问”的关键一步。我们需要把WSL中生成的rootCA.pem文件导入到Windows的“受信任的根证书颁发机构”存储区。4.1 定位根证书文件并复制到Windows首先在WSL中找到根证书的路径echo $(mkcert -CAROOT)/rootCA.pem通常路径是/home/你的用户名/.local/share/mkcert/rootCA.pem。WSL可以直接访问Windows的文件系统其挂载点在/mnt/下例如C盘是/mnt/c/。我们可以很方便地将证书文件复制到Windows的某个目录比如桌面。# 将根证书复制到Windows桌面假设你的Windows用户名是User cp $(mkcert -CAROOT)/rootCA.pem /mnt/c/Users/User/Desktop/rootCA.pem现在你应该能在Windows的桌面上看到一个rootCA.pem文件。4.2 通过证书管理器导入并信任在Windows上操作需要管理员权限。打开证书管理器按下Win R键输入certlm.msc然后回车。这是打开“本地计算机”证书管理器的命令。如果提示需要管理员权限请确认。另一种方式是右键点击开始菜单选择“运行”输入certlm.msc。导入证书在左侧控制台树中展开“受信任的根证书颁发机构”。右键点击“证书”文件夹选择“所有任务” - “导入...”。这会打开证书导入向导。点击“下一步”。点击“浏览”在文件类型下拉框中选择“所有文件 (*.*)”然后找到并选中你复制到桌面的rootCA.pem文件。点击“下一步”。在“证书存储”页面确保选择了“将所有的证书都放入下列存储”并且存储位置显示为“受信任的根证书颁发机构”。点击“下一步”。点击“完成”。你会看到一个“导入成功”的提示。验证导入在“受信任的根证书颁发机构” - “证书”文件夹内你应该能找到一个新的证书其“颁发者”和“颁发给”都是“mkcert development CA”。双击它可以查看详情。核心原理浏览器和大多数HTTP客户端如curl在Windows下的版本在验证SSL证书时会查询Windows系统的证书存储。我们将mkcert的根证书放在“受信任的根证书颁发机构”里就等于告诉系统“我完全信任这个CA颁发的任何证书”。因此当浏览器访问一个使用该CA签发证书的网站时验证链是完整且受信的自然不会弹出警告。4.3 浏览器层面的额外确认针对Chrome/Edge虽然系统级信任通常足够了但有时浏览器特别是Chrome和基于Chromium的Edge会有自己独立的证书缓存或管理策略。如果导入系统证书后访问仍有警告可以尝试完全关闭所有浏览器窗口再重新打开。在Chrome/Edge中访问chrome://settings/security或edge://settings/privacy搜索“管理证书”确保在“受信任的根证书颁发机构”列表中能看到“mkcert development CA”。清除浏览器SSL状态缓存这是一个强力但有效的操作Windows设置 - 网络和Internet - 代理 - 点击“手动代理设置”下的“局域网设置” - 在弹出的窗口中点击“局域网(LAN)设置”对话框底部的“确定”旁边的“高级”按钮实际上更直接的方法是在Windows搜索框输入“Internet选项”打开它。切换到“内容”选项卡。点击“清除SSL状态”按钮。然后重启浏览器。一个常见陷阱如果你之前访问过该本地地址并点击了“继续前往不安全网站”之类的选项浏览器可能会将这条“例外”规则缓存起来甚至优先于新安装的根证书。此时你需要清除该站点的缓存和Cookie或者在浏览器开发者工具的“安全”(Security)标签页里查看具体的证书错误信息。5. 配置Web服务器使用自定义证书证书准备好了系统也信任了接下来就是让Web服务器使用它们。这里以几个常见的开发服务器为例。5.1 使用简单的HTTP服务器如http-server或serve如果你使用Node.js的http-server或serve包启动时指定证书和密钥路径即可。# 使用 http-server npx http-server -S -C ~/certs/localhost2.pem -K ~/certs/localhost2-key.pem # 使用 serve npx serve -s --ssl-cert ~/certs/localhost2.pem --ssl-key ~/certs/localhost2-key.pem参数解释-S或--ssl: 启用HTTPS。-C或--ssl-cert: 指定证书文件路径。-K或--ssl-key: 指定私钥文件路径。服务器启动后它会监听https://localhost:8080默认端口可能不同。5.2 配置现代前端开发服务器Vite / Webpack Dev ServerVite在vite.config.js中配置import { defineConfig } from vite import fs from fs import path from path export default defineConfig({ server: { https: { key: fs.readFileSync(path.resolve(__dirname, certs/localhost2-key.pem)), cert: fs.readFileSync(path.resolve(__dirname, certs/localhost2.pem)) }, // 如果你需要通过IP访问比如手机测试需要配置host host: 0.0.0.0 } })Webpack Dev Server(在webpack.config.js中)const fs require(fs); const path require(path); module.exports { // ... 其他配置 devServer: { https: { key: fs.readFileSync(path.resolve(__dirname, certs/localhost2-key.pem)), cert: fs.readFileSync(path.resolve(__dirname, certs/localhost2.pem)) }, host: 0.0.0.0 } };5.3 配置Nginx服务器如果你在WSL中运行Nginx配置会稍微复杂一点但更接近生产环境。将证书和密钥文件放到Nginx的常用目录例如/etc/nginx/ssl/。sudo mkdir -p /etc/nginx/ssl sudo cp ~/certs/localhost2.pem /etc/nginx/ssl/ sudo cp ~/certs/localhost2-key.pem /etc/nginx/ssl/ # 设置正确的权限私钥应只对root可读 sudo chmod 600 /etc/nginx/ssl/localhost2-key.pem编辑Nginx的站点配置文件例如/etc/nginx/sites-available/default或新建一个server { listen 443 ssl http2; listen [::]:443 ssl http2; server_name localhost 127.0.0.1; # 指定证书和密钥路径 ssl_certificate /etc/nginx/ssl/localhost2.pem; ssl_certificate_key /etc/nginx/ssl/localhost2-key.pem; # 可选的SSL优化配置 ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512; ssl_prefer_server_ciphers off; root /var/www/html; index index.html index.htm; location / { try_files $uri $uri/ 404; } } # 将HTTP请求重定向到HTTPS可选但推荐 server { listen 80; listen [::]:80; server_name localhost 127.0.0.1; return 301 https://$server_name$request_uri; }测试配置并重载Nginxsudo nginx -t # 测试配置文件语法 sudo nginx -s reload # 重载配置现在你就可以在Windows的浏览器中访问https://localhost了。如果一切配置正确地址栏会显示安全的锁标志。6. 高级场景与疑难问题排查即使按照步骤操作也可能会遇到一些意外情况。这里汇总了一些常见问题及其解决方案。6.1 常见错误与解决方案速查表问题现象可能原因排查步骤与解决方案浏览器提示“您的连接不是私密连接”1. Windows未成功导入或信任根证书。2. 浏览器缓存了旧的证书错误信息。3. 证书的SAN主题备用名称不包含你正在访问的地址。1. 打开certlm.msc确认“受信任的根证书颁发机构”中存在“mkcert development CA”。2. 清除浏览器SSL状态缓存Internet选项-内容-清除SSL状态重启浏览器。3. 点击浏览器错误页面的“高级”查看证书详情确认证书颁发者和有效期。检查证书的“使用者可选名称”是否包含你访问的域名或IP。mkcert -install失败提示权限错误1. 没有使用sudo。2. WSL系统证书存储路径不可写。1. 使用sudo mkcert -install。2. 检查/usr/local/share/ca-certificates/目录权限。可以尝试手动操作sudo cp rootCA.pem /usr/local/share/ca-certificates/mkcert-root-ca.crt sudo update-ca-certificates。WSL内curl访问HTTPS失败但浏览器可以WSL内的Linux系统没有信任mkcert的根证书。确保在WSL中成功运行了mkcert -install。运行curl -v https://localhost查看详细错误通常会提示“self signed certificate in certificate chain”。通过WSL的IP如172.x.x.x访问失败1. 生成证书时未包含该IP地址。2. Windows防火墙或WSL网络配置阻止了访问。3. Web服务器未监听0.0.0.0。1. 重新生成证书将WSL的IP地址作为参数加入mkcert localhost 127.0.0.1 172.25.123.456。2. 在WSL内尝试curl https://172.x.x.x看是否通。如果不通检查服务器配置如Nginx的listen指令是否包含该IP或0.0.0.0。3. 在Windows的浏览器中直接用IP访问https://172.x.x.x。证书生成在WSL但Web服务器在Windows跨文件系统使用证书。将WSL中生成的.pem证书和密钥文件通过/mnt/c/路径复制到Windows的某个目录。然后在Windows的Web服务器配置中指向该Windows路径。注意WSL中的文件路径如~/certs/在Windows的软件中无法直接识别。错误ERROR: failed to generate cert: exit status 1可能是系统时间不正确或mkcert版本与系统不兼容。检查WSL系统时间date。如果时间偏差大在WSL中运行sudo hwclock -s尝试同步Windows主机时间。也可以尝试更新或重新安装mkcert。6.2 处理WSL2与Windows网络隔离问题WSL2的虚拟化网络架构带来一个常见问题从Windows访问WSL2中的应用不能简单地用localhost。虽然微软做了localhost转发但有时会失效特别是涉及特定端口或防火墙时。解决方案A使用WSL2的主机名在WSL2中运行hostname命令会得到一个类似MyComputerName的名字。在Windows的浏览器中你可以尝试访问https://MyComputerName。这需要你的证书包含了这个主机名或者在生成证书时使用通配符*.local但mkcert不支持通配符IP。解决方案B使用WSL2的IP地址最可靠如前所述获取WSL2的IPip addr show eth0将其加入证书的SAN列表然后在浏览器中用https://WSL-IP访问。这是最直接、受网络配置影响最小的方式。解决方案C配置Windows主机文件HOSTS如果你有一个自定义的本地开发域名如myapp.test你可以在Windows的C:\Windows\System32\drivers\etc\hosts文件中添加一行将其指向WSL2的IP172.25.123.456 myapp.test然后在WSL中为myapp.test生成证书并在浏览器中访问https://myapp.test。这模拟了生产环境的域名访问方式。6.3 证书管理与更新查看已安装的CA在WSL中mkcert -CAROOT查看路径。在Windows中通过certlm.msc查看。卸载不信任CA在WSL中运行mkcert -uninstall。这只会移除WSL Linux系统中的信任不会删除rootCA.pem文件本身。在Windows中需要手动打开certlm.msc在“受信任的根证书颁发机构” - “证书”里找到“mkcert development CA”右键删除。证书过期mkcert生成的证书默认有效期为825天约2年。你可以通过openssl x509 -in localhost2.pem -noout -dates查看有效期。过期后需要重新生成。添加新域名/IP如果项目新增了访问地址例如新增了一个本地测试域名只需重新运行mkcert命令将所有需要的域名和IP作为参数即可。新的证书文件会覆盖旧的如果同名记得重启你的Web服务器以加载新证书。整个流程走下来你会发现mkcert配合 WSL 为本地 HTTPS 开发提供了近乎完美的解决方案。它抽象了复杂的证书签发和信任流程让你能专注于开发本身。最关键的一步永远是把那个小小的rootCA.pem文件稳稳地放进 Windows 的信任仓库里这就像一把钥匙打开了本地开发环境与浏览器安全模型之间那扇常常令人困扰的门。
WSL2中配置mkcert实现本地HTTPS开发环境搭建指南
1. 项目概述为什么要在WSL里折腾mkcert如果你是一个在Windows上使用WSLWindows Subsystem for Linux进行Web开发的开发者那么“本地HTTPS”这个问题你肯定遇到过。无论是开发前端项目需要调用浏览器的某些高级API还是调试后端服务需要模拟真实的HTTPS环境一个有效的、被浏览器信任的SSL/TLS证书都是刚需。但每次去申请一个免费的公共证书或者自己用OpenSSL生成一个然后手动导入浏览器信任过程都相当繁琐。这就是mkcert这个工具闪亮登场的地方。它被设计用来解决一个核心痛点一键生成在本地开发环境中被浏览器和操作系统信任的证书。它的原理很简单就是在你的机器上安装一个本地的私有根证书颁发机构CA然后用这个CA去签发针对你本地域名比如localhost127.0.0.1myapp.test的证书。因为浏览器信任了你安装的根证书所以由它签发的所有子证书都会被自动信任不再有烦人的“不安全连接”警告。那么为什么要把mkcert部署在WSL环境里呢这背后有几个非常实际的考量。首先很多现代开发工具链和服务器比如Node.js的某些开发服务器、Go语言生态的工具本身就运行在WSL的Linux环境中在WSL内生成和使用证书路径和权限管理更自然与你的开发流程集成度更高。其次WSL2采用了虚拟化技术拥有独立的虚拟网络接口其IP地址通常是172.x.x.x与Windows主机的localhost并不完全等同。直接在WSL里为这个内部IP生成证书可以确保服务在WSL内部被访问时也是HTTPS的。最后这也是一种“环境隔离”的思路让开发依赖尽可能存在于WSL中保持Windows主机的相对干净。所以这个项目的目标非常明确在WSL的Linux环境中安装并运行mkcert生成用于本地开发的证书并将mkcert创建的根证书安装到Windows系统中最终实现在Windows的浏览器里无警告访问WSL中运行的HTTPS网站。整个过程涉及Linux环境配置、证书工具使用和Windows系统级信任操作是一个典型的跨系统开发生态搭建案例。2. 核心需求与前置准备解析在开始动手之前我们需要把整个流程拆解清楚并准备好必要的环境。这个项目不是简单的命令执行它连接了WSL和Windows两个系统任何一个环节的疏漏都可能导致最终失败。2.1 明确技术栈与依赖关系整个流程依赖于几个关键组件它们环环相扣WSL 2 环境这是我们的主战场。WSL 1由于网络架构不同在本地回环地址localhost的代理和访问上可能会有更多坑强烈建议使用WSL 2。你需要一个Linux发行版如Ubuntu、Debian等。mkcert工具核心工具用于创建本地CA和签发证书。它是一个用Go编写的单文件二进制程序不需要复杂的运行时环境。Windows 证书存储最终需要将mkcert生成的根证书一个.pem或.crt文件导入到Windows的“受信任的根证书颁发机构”存储中。这需要管理员权限。Web 服务器用于测试的Web服务器例如Nginx、Apache或者Node.js的http-server、serve亦或是像vite、webpack-dev-server这样的开发服务器。它们需要被配置为使用我们生成的证书文件。2.2 环境检查与准备工作在WSL终端中请依次执行以下检查确保基础环境就绪1. 确认WSL版本与网络打开Windows终端或PowerShell输入wsl --status。查看输出确认你使用的是WSL 2。同时在WSL内部运行ip addr show命令找到eth0接口记下它的IP地址通常是172.xx.xx.xx。这个地址是WSL虚拟机的内部IP我们后续可能会用到。2. 更新系统并安装基础工具在WSL终端中首先更新软件包列表并安装一些可能需要的工具比如curl和wget用于下载mkcert以及ca-certificates更新系统的CA证书包虽然不是必须但能避免一些潜在问题。sudo apt update sudo apt upgrade -y sudo apt install -y curl wget ca-certificates3. 规划证书存储路径这是一个容易被忽略但很重要的细节。mkcert默认会将生成的根证书和密钥放在$(mkcert -CAROOT)指示的目录通常是~/.local/share/mkcert或~/.mkcert。我们生成的网站证书也需要一个固定的地方存放。建议在用户目录下创建一个专用文件夹例如~/certs这样管理起来更清晰。mkdir -p ~/certs这个~/certs目录将是我们后续所有证书操作的工作区。注意权限问题。确保你对自己的家目录和~/certs有读写权限。mkcert在安装根证书时需要向系统证书存储写入文件这需要sudo权限。而生成网站证书通常在当前用户目录下即可。3. 在WSL中部署与配置mkcert环境准备好后我们就可以开始核心步骤了。这一步的目标是在WSL中成功安装mkcert并初始化本地CA。3.1 安装mkcert的几种方式及选择mkcert官方提供了多种安装方式选择哪种取决于你的网络环境和个人偏好。方式一使用Linux发行版的包管理器推荐如果可用这是最干净的方式。例如在Ubuntu/Debian上你可以通过系统维护的仓库安装。但请注意仓库中的版本可能不是最新的。sudo apt install -y mkcert安装完成后直接运行mkcert --version检查是否成功。方式二使用预编译的二进制文件通用方法这是最直接、能确保获取最新版的方法。我们使用curl从GitHub Releases下载。# 下载最新版的Linux二进制文件 curl -JLO https://github.com/FiloSottile/mkcert/releases/latest/download/mkcert-linux-amd64 # 下载完成后文件名为 mkcert-linux-amd64 # 将其重命名为 mkcert并移动到可执行路径 mv mkcert-linux-amd64 mkcert chmod x mkcert # 将 mkcert 移动到系统路径方便全局调用 sudo mv mkcert /usr/local/bin/再次运行mkcert --version确认。方式三通过Go工具安装如果你的WSL里已经安装了Go语言环境go version那么可以用这种方式go install filippo.io/mkcertlatest安装后二进制文件会在$GOPATH/bin或$HOME/go/bin下请确保该路径在你的$PATH环境变量中。实操心得我个人强烈推荐方式二。原因有三第一它不依赖系统仓库的更新节奏总能拿到最新版第二它不污染系统包管理器卸载时直接删除/usr/local/bin/mkcert文件即可第三过程透明下载的就是一个静态链接的二进制文件没有复杂的依赖。方式一虽然简单但遇到过旧版本在某些新系统上兼容性问题。方式三则引入了对Go环境的依赖不够纯粹。3.2 初始化本地证书颁发机构CA安装好mkcert后第一步不是直接生成网站证书而是初始化本地的CA。这个CA就是后续所有证书的“信任根源”。执行以下命令mkcert -install这个命令会做几件事在$(mkcert -CAROOT)目录下生成一对密钥文件根证书rootCA.pem和私钥rootCA-key.pem。尝试将根证书rootCA.pem安装到**当前系统即WSL的Linux系统**的信任存储中。对于基于Debian/Ubuntu的系统它会将证书复制到/usr/local/share/ca-certificates/目录然后调用update-ca-certificates命令让系统信任它。你可以通过以下命令验证CA是否创建成功以及其位置# 查看CA根证书存放目录 mkcert -CAROOT # 列出该目录下的文件 ls -la $(mkcert -CAROOT)你应该能看到rootCA.pem和rootCA-key.pem这两个文件。请务必妥善保管rootCA-key.pem它是你整个本地证书体系的“命门”一旦泄露任何人用它签发的证书都会被你的系统信任。重要提示mkcert -install在WSL中安装的根证书只对WSL内部的Linux环境生效。这意味着在WSL内部使用curl或wget访问一个由该CA签发的HTTPS网站时不会报证书错误。但是Windows系统及其上的浏览器如Chrome、Edge此时还完全不认识这个CA。这就是为什么我们后续必须把rootCA.pem文件手动导入Windows。3.3 为本地域名生成SSL证书现在我们可以用这个本地CA为我们需要的域名签发证书了。假设我们要为localhost和127.0.0.1以及WSL的内部IP172.25.123.456请替换为你自己的生成证书。切换到我们之前创建的证书目录然后执行生成命令cd ~/certs mkcert localhost 127.0.0.1 172.25.123.456命令执行后你会看到类似输出Created a new certificate valid for the following names - localhost - 127.0.0.1 - 172.25.123.456 The certificate is at ./localhost2.pem and the key at ./localhost2-key.pem ✅它生成了两个文件localhost2.pem这就是证书文件包含公钥。localhost2-key.pem这是对应的私钥文件。文件名解析mkcert默认以第一个域名这里是localhost为基础命名文件后面的2表示还有另外两个主题备用名称SAN。你也可以用-cert-file和-key-file参数来自定义输出文件名这对于管理多个项目的证书非常有用。mkcert -cert-file myapp.pem -key-file myapp-key.pem myapp.local 192.168.1.100注意事项生成的私钥文件*-key.pem是未加密的这意味着任何能访问到这个文件的人都可以使用它。在开发环境中这通常可以接受但切勿将其提交到版本控制系统如Git中。一个好的做法是在项目根目录的.gitignore文件中添加*.pem或*.key来忽略所有证书和密钥文件。4. 将根证书安装到Windows系统这是实现“在Windows浏览器中无警告访问”的关键一步。我们需要把WSL中生成的rootCA.pem文件导入到Windows的“受信任的根证书颁发机构”存储区。4.1 定位根证书文件并复制到Windows首先在WSL中找到根证书的路径echo $(mkcert -CAROOT)/rootCA.pem通常路径是/home/你的用户名/.local/share/mkcert/rootCA.pem。WSL可以直接访问Windows的文件系统其挂载点在/mnt/下例如C盘是/mnt/c/。我们可以很方便地将证书文件复制到Windows的某个目录比如桌面。# 将根证书复制到Windows桌面假设你的Windows用户名是User cp $(mkcert -CAROOT)/rootCA.pem /mnt/c/Users/User/Desktop/rootCA.pem现在你应该能在Windows的桌面上看到一个rootCA.pem文件。4.2 通过证书管理器导入并信任在Windows上操作需要管理员权限。打开证书管理器按下Win R键输入certlm.msc然后回车。这是打开“本地计算机”证书管理器的命令。如果提示需要管理员权限请确认。另一种方式是右键点击开始菜单选择“运行”输入certlm.msc。导入证书在左侧控制台树中展开“受信任的根证书颁发机构”。右键点击“证书”文件夹选择“所有任务” - “导入...”。这会打开证书导入向导。点击“下一步”。点击“浏览”在文件类型下拉框中选择“所有文件 (*.*)”然后找到并选中你复制到桌面的rootCA.pem文件。点击“下一步”。在“证书存储”页面确保选择了“将所有的证书都放入下列存储”并且存储位置显示为“受信任的根证书颁发机构”。点击“下一步”。点击“完成”。你会看到一个“导入成功”的提示。验证导入在“受信任的根证书颁发机构” - “证书”文件夹内你应该能找到一个新的证书其“颁发者”和“颁发给”都是“mkcert development CA”。双击它可以查看详情。核心原理浏览器和大多数HTTP客户端如curl在Windows下的版本在验证SSL证书时会查询Windows系统的证书存储。我们将mkcert的根证书放在“受信任的根证书颁发机构”里就等于告诉系统“我完全信任这个CA颁发的任何证书”。因此当浏览器访问一个使用该CA签发证书的网站时验证链是完整且受信的自然不会弹出警告。4.3 浏览器层面的额外确认针对Chrome/Edge虽然系统级信任通常足够了但有时浏览器特别是Chrome和基于Chromium的Edge会有自己独立的证书缓存或管理策略。如果导入系统证书后访问仍有警告可以尝试完全关闭所有浏览器窗口再重新打开。在Chrome/Edge中访问chrome://settings/security或edge://settings/privacy搜索“管理证书”确保在“受信任的根证书颁发机构”列表中能看到“mkcert development CA”。清除浏览器SSL状态缓存这是一个强力但有效的操作Windows设置 - 网络和Internet - 代理 - 点击“手动代理设置”下的“局域网设置” - 在弹出的窗口中点击“局域网(LAN)设置”对话框底部的“确定”旁边的“高级”按钮实际上更直接的方法是在Windows搜索框输入“Internet选项”打开它。切换到“内容”选项卡。点击“清除SSL状态”按钮。然后重启浏览器。一个常见陷阱如果你之前访问过该本地地址并点击了“继续前往不安全网站”之类的选项浏览器可能会将这条“例外”规则缓存起来甚至优先于新安装的根证书。此时你需要清除该站点的缓存和Cookie或者在浏览器开发者工具的“安全”(Security)标签页里查看具体的证书错误信息。5. 配置Web服务器使用自定义证书证书准备好了系统也信任了接下来就是让Web服务器使用它们。这里以几个常见的开发服务器为例。5.1 使用简单的HTTP服务器如http-server或serve如果你使用Node.js的http-server或serve包启动时指定证书和密钥路径即可。# 使用 http-server npx http-server -S -C ~/certs/localhost2.pem -K ~/certs/localhost2-key.pem # 使用 serve npx serve -s --ssl-cert ~/certs/localhost2.pem --ssl-key ~/certs/localhost2-key.pem参数解释-S或--ssl: 启用HTTPS。-C或--ssl-cert: 指定证书文件路径。-K或--ssl-key: 指定私钥文件路径。服务器启动后它会监听https://localhost:8080默认端口可能不同。5.2 配置现代前端开发服务器Vite / Webpack Dev ServerVite在vite.config.js中配置import { defineConfig } from vite import fs from fs import path from path export default defineConfig({ server: { https: { key: fs.readFileSync(path.resolve(__dirname, certs/localhost2-key.pem)), cert: fs.readFileSync(path.resolve(__dirname, certs/localhost2.pem)) }, // 如果你需要通过IP访问比如手机测试需要配置host host: 0.0.0.0 } })Webpack Dev Server(在webpack.config.js中)const fs require(fs); const path require(path); module.exports { // ... 其他配置 devServer: { https: { key: fs.readFileSync(path.resolve(__dirname, certs/localhost2-key.pem)), cert: fs.readFileSync(path.resolve(__dirname, certs/localhost2.pem)) }, host: 0.0.0.0 } };5.3 配置Nginx服务器如果你在WSL中运行Nginx配置会稍微复杂一点但更接近生产环境。将证书和密钥文件放到Nginx的常用目录例如/etc/nginx/ssl/。sudo mkdir -p /etc/nginx/ssl sudo cp ~/certs/localhost2.pem /etc/nginx/ssl/ sudo cp ~/certs/localhost2-key.pem /etc/nginx/ssl/ # 设置正确的权限私钥应只对root可读 sudo chmod 600 /etc/nginx/ssl/localhost2-key.pem编辑Nginx的站点配置文件例如/etc/nginx/sites-available/default或新建一个server { listen 443 ssl http2; listen [::]:443 ssl http2; server_name localhost 127.0.0.1; # 指定证书和密钥路径 ssl_certificate /etc/nginx/ssl/localhost2.pem; ssl_certificate_key /etc/nginx/ssl/localhost2-key.pem; # 可选的SSL优化配置 ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512; ssl_prefer_server_ciphers off; root /var/www/html; index index.html index.htm; location / { try_files $uri $uri/ 404; } } # 将HTTP请求重定向到HTTPS可选但推荐 server { listen 80; listen [::]:80; server_name localhost 127.0.0.1; return 301 https://$server_name$request_uri; }测试配置并重载Nginxsudo nginx -t # 测试配置文件语法 sudo nginx -s reload # 重载配置现在你就可以在Windows的浏览器中访问https://localhost了。如果一切配置正确地址栏会显示安全的锁标志。6. 高级场景与疑难问题排查即使按照步骤操作也可能会遇到一些意外情况。这里汇总了一些常见问题及其解决方案。6.1 常见错误与解决方案速查表问题现象可能原因排查步骤与解决方案浏览器提示“您的连接不是私密连接”1. Windows未成功导入或信任根证书。2. 浏览器缓存了旧的证书错误信息。3. 证书的SAN主题备用名称不包含你正在访问的地址。1. 打开certlm.msc确认“受信任的根证书颁发机构”中存在“mkcert development CA”。2. 清除浏览器SSL状态缓存Internet选项-内容-清除SSL状态重启浏览器。3. 点击浏览器错误页面的“高级”查看证书详情确认证书颁发者和有效期。检查证书的“使用者可选名称”是否包含你访问的域名或IP。mkcert -install失败提示权限错误1. 没有使用sudo。2. WSL系统证书存储路径不可写。1. 使用sudo mkcert -install。2. 检查/usr/local/share/ca-certificates/目录权限。可以尝试手动操作sudo cp rootCA.pem /usr/local/share/ca-certificates/mkcert-root-ca.crt sudo update-ca-certificates。WSL内curl访问HTTPS失败但浏览器可以WSL内的Linux系统没有信任mkcert的根证书。确保在WSL中成功运行了mkcert -install。运行curl -v https://localhost查看详细错误通常会提示“self signed certificate in certificate chain”。通过WSL的IP如172.x.x.x访问失败1. 生成证书时未包含该IP地址。2. Windows防火墙或WSL网络配置阻止了访问。3. Web服务器未监听0.0.0.0。1. 重新生成证书将WSL的IP地址作为参数加入mkcert localhost 127.0.0.1 172.25.123.456。2. 在WSL内尝试curl https://172.x.x.x看是否通。如果不通检查服务器配置如Nginx的listen指令是否包含该IP或0.0.0.0。3. 在Windows的浏览器中直接用IP访问https://172.x.x.x。证书生成在WSL但Web服务器在Windows跨文件系统使用证书。将WSL中生成的.pem证书和密钥文件通过/mnt/c/路径复制到Windows的某个目录。然后在Windows的Web服务器配置中指向该Windows路径。注意WSL中的文件路径如~/certs/在Windows的软件中无法直接识别。错误ERROR: failed to generate cert: exit status 1可能是系统时间不正确或mkcert版本与系统不兼容。检查WSL系统时间date。如果时间偏差大在WSL中运行sudo hwclock -s尝试同步Windows主机时间。也可以尝试更新或重新安装mkcert。6.2 处理WSL2与Windows网络隔离问题WSL2的虚拟化网络架构带来一个常见问题从Windows访问WSL2中的应用不能简单地用localhost。虽然微软做了localhost转发但有时会失效特别是涉及特定端口或防火墙时。解决方案A使用WSL2的主机名在WSL2中运行hostname命令会得到一个类似MyComputerName的名字。在Windows的浏览器中你可以尝试访问https://MyComputerName。这需要你的证书包含了这个主机名或者在生成证书时使用通配符*.local但mkcert不支持通配符IP。解决方案B使用WSL2的IP地址最可靠如前所述获取WSL2的IPip addr show eth0将其加入证书的SAN列表然后在浏览器中用https://WSL-IP访问。这是最直接、受网络配置影响最小的方式。解决方案C配置Windows主机文件HOSTS如果你有一个自定义的本地开发域名如myapp.test你可以在Windows的C:\Windows\System32\drivers\etc\hosts文件中添加一行将其指向WSL2的IP172.25.123.456 myapp.test然后在WSL中为myapp.test生成证书并在浏览器中访问https://myapp.test。这模拟了生产环境的域名访问方式。6.3 证书管理与更新查看已安装的CA在WSL中mkcert -CAROOT查看路径。在Windows中通过certlm.msc查看。卸载不信任CA在WSL中运行mkcert -uninstall。这只会移除WSL Linux系统中的信任不会删除rootCA.pem文件本身。在Windows中需要手动打开certlm.msc在“受信任的根证书颁发机构” - “证书”里找到“mkcert development CA”右键删除。证书过期mkcert生成的证书默认有效期为825天约2年。你可以通过openssl x509 -in localhost2.pem -noout -dates查看有效期。过期后需要重新生成。添加新域名/IP如果项目新增了访问地址例如新增了一个本地测试域名只需重新运行mkcert命令将所有需要的域名和IP作为参数即可。新的证书文件会覆盖旧的如果同名记得重启你的Web服务器以加载新证书。整个流程走下来你会发现mkcert配合 WSL 为本地 HTTPS 开发提供了近乎完美的解决方案。它抽象了复杂的证书签发和信任流程让你能专注于开发本身。最关键的一步永远是把那个小小的rootCA.pem文件稳稳地放进 Windows 的信任仓库里这就像一把钥匙打开了本地开发环境与浏览器安全模型之间那扇常常令人困扰的门。
