mkcert v1.4.4 实战：Vue 3 + Uniapp 本地 HTTPS 配置，3 分钟解决摄像头 API 调用
现代前端开发中，越来越多的浏览器 API 要求运行在安全上下文（Secure Context）中，例如摄像头、地理位置、剪贴板等。这意味着开发者必须在 HTTPS 环境下才能正常调用这些 API。本文将详细介绍如何使用 mkcert v1.4.4 为 Vue 3 和 Uniapp 项目快速配置本地 HTTPS 开发环境，解决这些 API 的调用问题。
1. 为什么需要本地 HTTPS 开发环境
在本地开发过程中，我们通常会遇到以下几种情况需要 HTTPS：
- 浏览器安全策略限制：如
getUserMedia（摄像头/麦克风）、Geolocation API等 - 第三方服务集成：如 OAuth 登录、支付接口等
- PWA 功能测试：Service Worker 必须在 HTTPS 下运行
- 混合内容警告：当页面通过 HTTPS 加载但请求 HTTP 资源时
提示：Chrome 从 92 版本开始，即使是在 localhost 环境下，某些敏感 API 也要求 HTTPS 才能正常工作。
2. mkcert 简介与安装
mkcert 是一个零配置的工具，用于创建本地开发用的可信 HTTPS 证书。它的主要优势在于：
- 自动创建本地证书颁发机构（CA）
- 生成的证书被操作系统和浏览器信任
- 支持多域名和 IP 地址
- 无需手动配置证书信任
2.1 安装 mkcert
根据你的操作系统选择对应的安装方式：
macOS (Homebrew):
brew install mkcert brew install nss # 如果你使用 FirefoxWindows (Chocolatey):
choco install mkcertLinux:
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 或更高版本3. 生成并信任本地证书
3.1 创建本地 CA
首先，我们需要在系统中安装一个本地证书颁发机构：
mkcert -install这个命令会在你的系统中创建一个本地 CA，并自动被大多数浏览器和操作系统信任。
3.2 为项目生成证书
接下来，为你的开发环境生成证书。通常我们会为 localhost 和 127.0.0.1 生成证书：
mkcert -key-file key.pem -cert-file cert.pem localhost 127.0.0.1 ::1这将生成两个文件：
key.pem：私钥文件cert.pem：证书文件
注意：如果你使用自定义域名开发（如
myapp.test），需要将其添加到证书中：mkcert -key-file key.pem -cert-file cert.pem localhost 127.0.0.1 ::1 myapp.test
4. Vue 3 (Vite) 项目配置
对于使用 Vite 构建的 Vue 3 项目，配置 HTTPS 非常简单。
4.1 基本配置
将生成的key.pem和cert.pem文件复制到项目根目录下，然后修改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, 'key.pem')), cert: fs.readFileSync(path.resolve(__dirname, 'cert.pem')) }, host: 'localhost', port: 443 // 标准 HTTPS 端口 } })4.2 解决常见问题
问题1：端口冲突如果 443 端口被占用，可以改用其他端口（如 8443），但需要注意：
- 某些浏览器会强制将 8443 视为非标准端口
- 可能需要手动输入
https://localhost:8443
问题2：HMR (热更新) 失效在vite.config.js中添加：
server: { hmr: { protocol: 'wss', host: 'localhost' } }5. Uniapp 项目配置
Uniapp 的配置略有不同，主要通过修改manifest.json文件实现。
5.1 基本配置
在项目根目录的manifest.json文件中，找到或添加h5配置：
{ "h5": { "devServer": { "https": { "key": "-----BEGIN PRIVATE KEY-----\n...你的私钥内容...\n-----END PRIVATE KEY-----", "cert": "-----BEGIN CERTIFICATE-----\n...你的证书内容...\n-----END CERTIFICATE-----" }, "port": 443 } } }注意：这里需要将
key.pem和cert.pem文件的内容直接粘贴到配置中，包括-----BEGIN...和-----END...标记。
5.2 简化配置技巧
为了避免每次更新证书都要修改manifest.json，可以创建一个脚本自动生成配置：
// scripts/gen-https-config.js const fs = require('fs') const path = require('path') const key = fs.readFileSync(path.join(__dirname, '../key.pem'), 'utf8') const cert = fs.readFileSync(path.join(__dirname, '../cert.pem'), 'utf8') const config = { h5: { devServer: { https: { key, cert }, port: 443 } } } fs.writeFileSync( path.join(__dirname, '../src/manifest.json'), JSON.stringify(config, null, 2) )然后在package.json中添加脚本：
{ "scripts": { "gen:https": "node scripts/gen-https-config.js" } }6. 浏览器信任问题解决
即使使用了 mkcert，有时浏览器仍会显示警告。以下是常见问题的解决方法：
6.1 Chrome 安全警告
如果 Chrome 仍然显示 "Not Secure"：
- 在地址栏输入
chrome://flags/#allow-insecure-localhost - 将 "Allow invalid certificates for resources loaded from localhost" 设置为 Enabled
- 重启 Chrome
6.2 Firefox 证书信任
Firefox 使用自己的证书存储：
- 打开 Firefox 设置
- 搜索 "certificates"
- 点击 "View Certificates"
- 在 "Authorities" 标签中导入
rootCA-key.pem（通常位于~/.local/share/mkcert或%APPDATA%\mkcert）
7. 真机调试配置
要在移动设备上测试 HTTPS 功能，需要确保设备能访问开发机，并信任证书。
7.1 查找开发机 IP
# macOS/Linux ifconfig | grep "inet " # Windows ipconfig记下本地局域网 IP（通常是 192.168.x.x）
7.2 移动设备信任证书
在开发机上运行：
mkcert -install mkcert -pkcs12 localhost 192.168.x.x这会生成
localhost.p12文件将
localhost.p12发送到移动设备并安装在移动设备浏览器中访问
https://192.168.x.x:443
8. 高级技巧与自动化
8.1 一键脚本
创建setup-https.sh脚本自动化整个过程：
#!/bin/bash # 安装 mkcert 如果尚未安装 if ! command -v mkcert &> /dev/null; then echo "Installing mkcert..." brew install mkcert # 或者使用其他系统的安装命令 fi # 创建并信任 CA mkcert -install # 生成证书 mkcert -key-file key.pem -cert-file cert.pem localhost 127.0.0.1 ::1 # 为 Vue 项目创建配置文件 cat > vite.config.js <<EOL 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, 'key.pem')), cert: fs.readFileSync(path.resolve(__dirname, 'cert.pem')) }, host: 'localhost', port: 443 } }) EOL echo "HTTPS setup complete!"8.2 使用环境变量
区分开发和生产环境：
// vite.config.js import { defineConfig, loadEnv } from 'vite' export default defineConfig(({ mode }) => { const env = loadEnv(mode, process.cwd()) const httpsConfig = env.VITE_HTTPS === 'true' ? { key: fs.readFileSync('./key.pem'), cert: fs.readFileSync('./cert.pem') } : false return { server: { https: httpsConfig } } })然后在.env.development中添加：
VITE_HTTPS=true9. 常见问题排查
9.1 证书不受信任
- 确保运行了
mkcert -install - 检查证书是否过期（默认有效期 2 年）
- 尝试重启浏览器
9.2 HMR 不工作
- 确保配置了正确的 WebSocket 协议（wss）
- 检查防火墙设置，确保端口未被阻止
9.3 跨域问题
配置代理或 CORS 头：
// vite.config.js server: { proxy: { '/api': { target: 'https://api.example.com', changeOrigin: true, secure: false } }, headers: { 'Access-Control-Allow-Origin': '*' } }10. 最佳实践与安全建议
不要将证书提交到版本控制：在
.gitignore中添加：*.pem key.pem cert.pem定期更新证书：虽然 mkcert 证书默认有效期为 2 年，但建议每年更新一次
开发环境专用：切勿将这些证书用于生产环境
团队协作：确保团队成员都安装了相同的 CA 证书
多项目隔离：为每个项目创建单独的证书，而不是共用 localhost 证书
