前端工程化 / 系统课时

启用本地 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}

bash
mkcert -install
mkdir -p .cert
mkcert -key-file .cert/localhost-key.pem -cert-file .cert/localhost.pem localhost 127.0.0.1 ::1

预期输出

text
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:

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

启动开发服务器:

bash
npm run dev

预期输出

text
VITE v<VERSION> ready in <TIME> ms
Local: https://localhost:5173/

浏览器地址必须使用 https://localhost:5173/。再用状态码检查服务是否可访问:

bash
curl -sS -o /dev/null -w '%{http_code}\n' https://localhost:5173/

预期输出

text
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;仅在开发电脑上信任并不会自动传播。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

启用本地 HTTPS

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通