前端工程化 / 系统课时
启用本地 HTTPS
启用本地 HTTPS
本课完成 Vite 开发服务器的本地 HTTPS 配置,并建立一套可复用的验证与排障顺序。完成后,你能让浏览器通过受信任证书访问项目,并快速区分证书不受信任、访问协议错误和混合内容三类问题。
学习目标
- 为本地域名生成证书,并在
vite.config.ts中配置私钥与证书 - 验证 HTTPS 服务、证书信任和访问协议是否一致
- 定位浏览器证书警告、协议不匹配与混合内容错误
选择本地证书方案
Vite 的 server.https 接收 Node.js HTTPS 服务器选项,因此启用 HTTPS 时需要提供有效证书。官方也提供 @vitejs/plugin-basic-ssl 作为快速方案,它会生成并缓存自签名证书,但这类证书默认不受浏览器信任;需要稳定开发体验时,更适合使用本机信任的本地 CA 证书。:contentReference[oaicite:0]{index=0}
| 方案 | 适用场景 | 主要边界 |
|---|---|---|
mkcert 本地 CA |
日常开发、登录回调、安全上下文 API | 每台开发设备都要安装本地 CA |
@vitejs/plugin-basic-ssl |
临时验证 HTTPS 是否能启动 | 浏览器通常仍会显示证书警告 |
| 团队统一证书 | 固定开发域名、多人联调 | 私钥分发和轮换必须受控 |
生成并配置证书
以下命令假设系统已安装 mkcert。先安装本地 CA,再把证书写入项目的 .cert 目录;证书名称必须覆盖实际访问的主机名,否则浏览器仍会报告名称不匹配。mkcert 会把本地 CA 加入系统信任库,但不会自动修改 Vite 配置。:contentReference[oaicite:1]{index=1}
mkcert -install
mkdir -p .cert
mkcert -key-file .cert/localhost-key.pem -cert-file .cert/localhost.pem localhost 127.0.0.1 ::1预期输出
Created a new local CA
The local CA is now installed in the system trust store
The certificate is at ".cert/localhost.pem" and the key at ".cert/localhost-key.pem"不同系统的提示文字可能不同,只要证书文件和私钥文件成功生成即可。随后创建或修改 vite.config.ts:
import { readFileSync } from 'node:fs'
import { fileURLToPath } from 'node:url'
import { resolve } from 'node:path'
import { defineConfig } from 'vite'
const projectRoot = fileURLToPath(new URL('.', import.meta.url))
export default defineConfig({
server: {
host: 'localhost',
port: 5173,
strictPort: true,
https: {
key: readFileSync(resolve(projectRoot, '.cert/localhost-key.pem')),
cert: readFileSync(resolve(projectRoot, '.cert/localhost.pem')),
},
},
})这段配置把证书内容传给 Vite 的 HTTPS 服务器。strictPort: true 可避免端口被占用时自动切换到其他端口,从而让证书验证、回调地址和后续排障保持一致。Vite 官方文档确认 server.https 会把对象传给 https.createServer()。:contentReference[oaicite:2]{index=2}
启动并验证 HTTPS
启动开发服务器:
npm run dev预期输出
VITE v<VERSION> ready in <TIME> ms
Local: https://localhost:5173/浏览器地址必须使用 https://localhost:5173/。再用状态码检查服务是否可访问:
curl -sS -o /dev/null -w '%{http_code}\n' https://localhost:5173/预期输出
200若 curl 报证书错误而浏览器正常,通常是当前 curl 使用的信任库与系统浏览器不同;不要长期用 -k 掩盖问题,应确认本地 CA 是否被对应工具信任。若浏览器仍提示风险,先重启浏览器,再检查证书是否包含当前访问的主机名。
按现象定位三类问题
证书不受信任
页面能建立 TLS 连接,但浏览器显示隐私警告,说明证书链没有被当前浏览器信任。重新执行 mkcert -install、重启浏览器,并确认没有误把其他机器生成的证书直接复制过来。rootCA-key.pem 具有签发本机受信任证书的能力,绝不能提交仓库或共享。:contentReference[oaicite:3]{index=3}
访问协议不一致
Vite 已启用 HTTPS 后,仍访问 http://localhost:5173/,客户端会按明文 HTTP 发送请求,而服务器等待 TLS 握手,结果通常表现为连接失败或协议错误。反过来,未启用 HTTPS 却访问 https:// 也会失败。排查时先核对终端打印的 Local 地址,再核对浏览器地址栏协议。
混合内容
HTTPS 页面若直接请求普通 HTTP 接口,fetch()、XHR、脚本等主动内容通常会被浏览器阻止;HTTPS 页面也不应直接建立 ws:// 连接,而应使用 wss://。最稳妥的开发方式是让前端使用 /api、/socket 等同源路径,再由 Vite 代理到内部 HTTP 或 WebSocket 服务。:contentReference[oaicite:4]{index=4}
安全边界
证书私钥只用于本地开发,.cert 目录应加入 .gitignore。不要把本地 CA 私钥、开发证书或 secure: false 一类绕过验证的做法带入生产环境。移动设备或其他电脑访问时,还需要在那台设备上单独安装并信任 CA;仅在开发电脑上信任并不会自动传播。