mkcert v1.4.4 配置 Vue/UniApp 本地 HTTPS：3 分钟解决摄像头 API 调用限制

mkcert v1.4.4 配置 Vue/UniApp 本地 HTTPS：3 分钟解决摄像头 API 调用限制

现代前端开发中，越来越多的浏览器 API 要求运行在安全上下文（Secure Context）中，这意味着开发者必须在 HTTPS 环境下才能调用这些 API。常见的受限 API 包括：

• 摄像头和麦克风访问（getUserMedia）
• 地理位置信息（Geolocation API）
• 设备方向与运动传感器
• 支付请求 API
• Web Bluetooth 和 Web USB

对于 Vue 和 UniApp 开发者来说，这带来了一个现实问题：如何在本地开发环境中快速启用 HTTPS，而不必经历繁琐的证书申请流程？本文将介绍如何使用 mkcert 这一工具，在 3 分钟内为你的项目配置可信的本地 HTTPS 环境。

1. mkcert 简介与安装

mkcert 是一个由 Filippo Valsorda 开发的零配置工具，专门用于生成本地开发环境信任的 SSL/TLS 证书。它的核心优势在于：

1. 自动信任：生成的证书会被自动添加到系统的信任存储中
2. 跨平台支持：Windows、macOS 和 Linux 均可使用
3. 简单易用：无需复杂的配置或命令行参数

1.1 安装 mkcert

根据你的操作系统，选择以下安装方式之一：

macOS (Homebrew)

brew install mkcert brew install nss # 如果你使用 Firefox

Windows (Chocolatey)

choco install mkcert

Linux

sudo apt install libnss3-tools 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

安装完成后，验证版本：

mkcert -version # 应输出类似：v1.4.4

2. 生成并安装本地 CA

mkcert 的工作原理是先创建一个本地证书颁发机构（CA），然后用这个 CA 签发具体的域名证书。这样浏览器会信任由这个 CA 签发的所有证书。

2.1 安装本地 CA

运行以下命令：

mkcert -install

这个命令会在你的系统中创建一个名为 "mkcert development CA" 的根证书，并自动将其添加到系统的信任存储中。

注意：在 Windows 上，可能会弹出用户账户控制（UAC）提示，需要管理员权限来修改证书存储。

2.2 验证 CA 安装

• macOS：打开"钥匙串访问"应用，在"系统"钥匙串的"证书"类别中应该能看到 "mkcert development CA"
• Windows：运行certmgr.msc，在"受信任的根证书颁发机构"中应该能看到该证书

3. 为项目生成证书

现在我们可以为具体的开发域名生成证书了。对于本地开发，最常见的域名是localhost和127.0.0.1。

3.1 生成证书文件

在项目根目录下运行：

mkcert localhost 127.0.0.1 ::1

这将生成两个文件：

• localhost+2-key.pem：私钥文件
• localhost+2.pem：证书文件

提示：如果你想使用自定义域名（如myapp.test），只需将其添加到命令中：mkcert myapp.test localhost 127.0.0.1

3.2 重命名证书文件（可选）

为了更好的可读性，建议将生成的文件重命名：

mv localhost+2-key.pem localhost-key.pem mv localhost+2.pem localhost-cert.pem

4. Vue 项目配置

根据你使用的 Vue 版本和构建工具，配置方式有所不同。

4.1 Vue 2 (Webpack)

在项目根目录创建或修改vue.config.js：

const 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.js：

import { 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，你应该能看到：

1. 地址栏显示安全锁图标
2. 点击锁图标可以查看证书详情
3. 可以正常调用摄像头、地理位置等敏感 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 localhost+2-key.pem localhost-key.pem mv localhost+2.pem localhost-cert.pem echo "HTTPS 证书已设置完成！"

7.2 使用说明

chmod +x setup-https.sh ./setup-https.sh

8. 常见问题解决

8.1 Chrome 仍然显示不安全

尝试以下方法：

1. 访问chrome://flags/#allow-insecure-localhost并启用该选项
2. 清除浏览器缓存
3. 确保没有使用--ignore-certificate-errors标志启动 Chrome

8.2 移动设备无法访问

要在移动设备上测试：

1. 确保设备和开发电脑在同一局域网
2. 使用电脑的局域网 IP 而非 localhost
3. 在移动设备上安装 mkcert CA 证书：

   mkcert -CAROOT

   将显示的目录中的rootCA.pem发送到移动设备并安装

8.3 证书过期

mkcert 生成的证书默认有效期为 2 年。如需更新，只需重新运行生成命令。

9. 高级配置选项

9.1 自定义域名

如果你使用自定义域名（如myapp.test）进行开发：

1. 编辑/etc/hosts文件（Windows 为C:\Windows\System32\drivers\etc\hosts）：

   127.0.0.1 myapp.test

2. 生成证书：

   mkcert myapp.test

3. 更新开发服务器配置，使用新证书并设置host: 'myapp.test'

9.2 多域名证书

可以为多个域名生成单个证书：

mkcert myapp.test api.myapp.test localhost 127.0.0.1 ::1

9.3 通配符证书

支持通配符子域名：

mkcert "*.myapp.test"

10. 安全注意事项

虽然 mkcert 极大简化了本地 HTTPS 配置，但需要注意：

1. 不要将生成的证书用于生产环境：这些证书仅适用于本地开发
2. 保护私钥文件：localhost-key.pem是敏感文件，不应提交到版本控制
3. 定期更新 CA 证书：团队成员应使用相同的 CA 证书

建议将证书文件添加到.gitignore：

# SSL certificates localhost-key.pem localhost-cert.pem

11. 替代方案比较

除了 mkcert，还有其他本地 HTTPS 解决方案：

对于大多数 Vue 和 UniApp 开发者，mkcert 提供了最佳平衡点：简单易用且高度可靠。