mkcert v1.4.4 配置 Vue/UniApp 本地 HTTPS3 分钟解决摄像头 API 调用限制现代前端开发中越来越多的浏览器 API 要求运行在安全上下文Secure Context中这意味着开发者必须在 HTTPS 环境下才能调用这些 API。常见的受限 API 包括摄像头和麦克风访问getUserMedia地理位置信息Geolocation API设备方向与运动传感器支付请求 APIWeb Bluetooth 和 Web USB对于 Vue 和 UniApp 开发者来说这带来了一个现实问题如何在本地开发环境中快速启用 HTTPS而不必经历繁琐的证书申请流程本文将介绍如何使用 mkcert 这一工具在 3 分钟内为你的项目配置可信的本地 HTTPS 环境。1. mkcert 简介与安装mkcert 是一个由 Filippo Valsorda 开发的零配置工具专门用于生成本地开发环境信任的 SSL/TLS 证书。它的核心优势在于自动信任生成的证书会被自动添加到系统的信任存储中跨平台支持Windows、macOS 和 Linux 均可使用简单易用无需复杂的配置或命令行参数1.1 安装 mkcert根据你的操作系统选择以下安装方式之一macOS (Homebrew)brew install mkcert brew install nss # 如果你使用 FirefoxWindows (Chocolatey)choco install mkcertLinuxsudo apt install libnss3-tools curl -JLO https://dl.filippo.io/mkcert/latest?forlinux/amd64 chmod x mkcert-v*-linux-amd64 sudo mv mkcert-v*-linux-amd64 /usr/local/bin/mkcert安装完成后验证版本mkcert -version # 应输出类似v1.4.42. 生成并安装本地 CAmkcert 的工作原理是先创建一个本地证书颁发机构CA然后用这个 CA 签发具体的域名证书。这样浏览器会信任由这个 CA 签发的所有证书。2.1 安装本地 CA运行以下命令mkcert -install这个命令会在你的系统中创建一个名为 mkcert development CA 的根证书并自动将其添加到系统的信任存储中。注意在 Windows 上可能会弹出用户账户控制UAC提示需要管理员权限来修改证书存储。2.2 验证 CA 安装macOS打开钥匙串访问应用在系统钥匙串的证书类别中应该能看到 mkcert development CAWindows运行certmgr.msc在受信任的根证书颁发机构中应该能看到该证书3. 为项目生成证书现在我们可以为具体的开发域名生成证书了。对于本地开发最常见的域名是localhost和127.0.0.1。3.1 生成证书文件在项目根目录下运行mkcert localhost 127.0.0.1 ::1这将生成两个文件localhost2-key.pem私钥文件localhost2.pem证书文件提示如果你想使用自定义域名如myapp.test只需将其添加到命令中mkcert myapp.test localhost 127.0.0.13.2 重命名证书文件可选为了更好的可读性建议将生成的文件重命名mv localhost2-key.pem localhost-key.pem mv localhost2.pem localhost-cert.pem4. Vue 项目配置根据你使用的 Vue 版本和构建工具配置方式有所不同。4.1 Vue 2 (Webpack)在项目根目录创建或修改vue.config.jsconst fs require(fs) const path require(path) module.exports { devServer: { https: { key: fs.readFileSync(path.resolve(__dirname, localhost-key.pem)), cert: fs.readFileSync(path.resolve(__dirname, localhost-cert.pem)) }, port: 8080, host: localhost } }4.2 Vue 3 (Vite)修改vite.config.jsimport { defineConfig } from vite import vue from vitejs/plugin-vue import fs from fs import path from path export default defineConfig({ plugins: [vue()], server: { https: { key: fs.readFileSync(path.resolve(__dirname, localhost-key.pem)), cert: fs.readFileSync(path.resolve(__dirname, localhost-cert.pem)) }, port: 8080, host: localhost } })5. UniApp 项目配置UniApp 的配置略有不同需要在manifest.json中直接嵌入证书内容。5.1 获取证书内容将证书文件内容转换为单行字符串注意保留\n换行符# Linux/macOS cert$(sed :a;N;$!ba;s/\n/\\n/g localhost-cert.pem) key$(sed :a;N;$!ba;s/\n/\\n/g localhost-key.pem) # Windows (PowerShell) $cert Get-Content localhost-cert.pem -Raw | ForEach-Object { $_ -replace n,\n } $key Get-Content localhost-key.pem -Raw | ForEach-Object { $_ -replace n,\n }5.2 配置 manifest.json在manifest.json的h5部分添加h5: { devServer: { https: { cert: -----BEGIN CERTIFICATE-----\n...完整证书内容...\n-----END CERTIFICATE-----, key: -----BEGIN PRIVATE KEY-----\n...完整私钥内容...\n-----END PRIVATE KEY----- } } }6. 验证 HTTPS 配置启动开发服务器后在浏览器中访问https://localhost:8080你应该能看到地址栏显示安全锁图标点击锁图标可以查看证书详情可以正常调用摄像头、地理位置等敏感 API如果遇到浏览器警告请检查是否正确地运行了mkcert -install证书是否已正确添加到系统信任存储开发服务器是否使用了正确的证书文件7. 自动化脚本一键配置为了简化流程可以创建一个自动化脚本7.1 创建 setup-https.sh#!/bin/bash # 安装 mkcert 如果尚未安装 if ! command -v mkcert /dev/null; then echo 安装 mkcert... brew install mkcert || sudo apt install -y mkcert || choco install mkcert mkcert -install fi # 生成证书 echo 生成本地证书... mkcert localhost 127.0.0.1 ::1 # 重命名证书文件 mv localhost2-key.pem localhost-key.pem mv localhost2.pem localhost-cert.pem echo HTTPS 证书已设置完成7.2 使用说明chmod x setup-https.sh ./setup-https.sh8. 常见问题解决8.1 Chrome 仍然显示不安全尝试以下方法访问chrome://flags/#allow-insecure-localhost并启用该选项清除浏览器缓存确保没有使用--ignore-certificate-errors标志启动 Chrome8.2 移动设备无法访问要在移动设备上测试确保设备和开发电脑在同一局域网使用电脑的局域网 IP 而非 localhost在移动设备上安装 mkcert CA 证书mkcert -CAROOT将显示的目录中的rootCA.pem发送到移动设备并安装8.3 证书过期mkcert 生成的证书默认有效期为 2 年。如需更新只需重新运行生成命令。9. 高级配置选项9.1 自定义域名如果你使用自定义域名如myapp.test进行开发编辑/etc/hosts文件Windows 为C:\Windows\System32\drivers\etc\hosts127.0.0.1 myapp.test生成证书mkcert myapp.test更新开发服务器配置使用新证书并设置host: myapp.test9.2 多域名证书可以为多个域名生成单个证书mkcert myapp.test api.myapp.test localhost 127.0.0.1 ::19.3 通配符证书支持通配符子域名mkcert *.myapp.test10. 安全注意事项虽然 mkcert 极大简化了本地 HTTPS 配置但需要注意不要将生成的证书用于生产环境这些证书仅适用于本地开发保护私钥文件localhost-key.pem是敏感文件不应提交到版本控制定期更新 CA 证书团队成员应使用相同的 CA 证书建议将证书文件添加到.gitignore# SSL certificates localhost-key.pem localhost-cert.pem11. 替代方案比较除了 mkcert还有其他本地 HTTPS 解决方案工具优点缺点mkcert零配置自动信任支持多域名需要安装vite-plugin-basic-ssl无需安装额外工具Vite 内置每次启动生成新证书浏览器会警告OpenSSL高度可定制配置复杂需要手动信任证书ngrok提供公开 HTTPS URL需要网络连接有速率限制对于大多数 Vue 和 UniApp 开发者mkcert 提供了最佳平衡点简单易用且高度可靠。