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?forlinux/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.test4. Vue 3 (Vite) 项目配置对于使用 Vite 构建的 Vue 3 项目配置 HTTPS 非常简单。4.1 基本配置将生成的key.pem和cert.pem文件复制到项目根目录下然后修改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, key.pem)), cert: fs.readFileSync(path.resolve(__dirname, cert.pem)) }, host: localhost, port: 443 // 标准 HTTPS 端口 } })4.2 解决常见问题问题1端口冲突如果 443 端口被占用可以改用其他端口如 8443但需要注意某些浏览器会强制将 8443 视为非标准端口可能需要手动输入https://localhost:8443问题2HMR (热更新) 失效在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重启 Chrome6.2 Firefox 证书信任Firefox 使用自己的证书存储打开 Firefox 设置搜索 certificates点击 View Certificates在 Authorities 标签中导入rootCA-key.pem通常位于~/.local/share/mkcert或%APPDATA%\mkcert7. 真机调试配置要在移动设备上测试 HTTPS 功能需要确保设备能访问开发机并信任证书。7.1 查找开发机 IP# macOS/Linux ifconfig | grep inet # Windows ipconfig记下本地局域网 IP通常是 192.168.x.x7.2 移动设备信任证书在开发机上运行mkcert -install mkcert -pkcs12 localhost 192.168.x.x这会生成localhost.p12文件将localhost.p12发送到移动设备并安装在移动设备浏览器中访问https://192.168.x.x:4438. 高级技巧与自动化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_HTTPStrue9. 常见问题排查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 证书