Vite 开发环境配置 HTTPS|umrcheng的博客

1. 插件概述

@vitejs/plugin-basic-ssl 是 Vite 官方提供的轻量级 SSL 插件，用于快速为 Vite 开发服务器启用 HTTPS 服务，无需手动配置 SSL 证书——插件会自动生成并使用自签名的 SSL 证书，适用于本地开发场景（如需要 HTTPS 环境调试 PWA、支付回调、跨域等功能）。

核心特性

零配置快速启用 HTTPS；
自动生成/管理自签名 SSL 证书；
兼容 Vite 2.x+ 所有版本；
跨平台支持（Windows/macOS/Linux）。

2. 安装

前置条件

Node.js ≥ 14.18.0
Vite ≥ 2.0.0

安装命令

根据你的包管理器选择对应命令：

# npm
npm install @vitejs/plugin-basic-ssl -D

# yarn
yarn add @vitejs/plugin-basic-ssl -D

# pnpm
pnpm add @vitejs/plugin-basic-ssl -D

3. 基本使用

3.1 Vite 配置文件（vite.config.js/ts）

在 Vite 配置文件中引入并注册插件即可启用 HTTPS：

// vite.config.ts (TypeScript 示例)
import { defineConfig } from "vite";
import basicSsl from "@vitejs/plugin-basic-ssl";

export default defineConfig({
  plugins: [
    basicSsl(), // 注册插件，无额外配置即可启用 HTTPS
  ],
});

// vite.config.js (JavaScript 示例)
import { defineConfig } from "vite";
import basicSsl from "@vitejs/plugin-basic-ssl";

export default defineConfig({
  plugins: [basicSsl()],
});

3.2 启动开发服务器

启动 Vite 开发服务器后，访问地址会自动从 http://localhost:5173 变为 https://localhost:5173：

# 启动开发服务器
npm run dev

启动成功后终端会输出类似日志：

  VITE v5.0.0  ready in 100 ms

  ➜  Local:   https://localhost:5173/
  ➜  Network: use --host to expose

4. 高级配置

插件支持传入可选配置项，自定义证书相关行为：

4.1 配置项说明

配置项	类型	默认值	说明
`certDir`	`string`	`~/.vite-plugin-ssl`	证书存储目录（绝对路径/相对路径均可）
`hosts`	`string[]`	`['localhost', '127.0.0.1']`	证书中包含的域名/IP（解决多域名/IP 访问时的证书警告）

4.2 自定义配置示例

// vite.config.ts
import { defineConfig } from "vite";
import basicSsl from "@vitejs/plugin-basic-ssl";
import path from "path";

export default defineConfig({
  plugins: [
    basicSsl({
      // 自定义证书存储目录
      certDir: path.resolve(__dirname, "./ssl"),
      // 新增自定义域名/IP（如本地测试域名、局域网IP）
      hosts: ["localhost", "127.0.0.1", "test.local", "192.168.1.100"],
    }),
  ],
});

5. 解决浏览器证书警告

由于插件使用自签名证书，首次访问 HTTPS 地址时，浏览器会提示「您的连接不是私密连接」，需手动信任证书：

5.1 Chrome/Edge 浏览器

访问 https://localhost:5173，出现警告后点击「高级」；
选择「继续访问 localhost（不安全）」（不同版本文案略有差异）；
（可选）长期信任：将证书添加到系统信任列表（参考下方「进阶：永久信任证书」）。

5.2 Firefox 浏览器

访问 https://localhost:5173，出现警告后点击「高级」；
选择「添加例外」→「确认安全例外」。

5.3 进阶：永久信任证书

若不想每次启动都手动确认，可将插件生成的证书添加到系统信任列表：

找到证书存储目录（默认 ~/.vite-plugin-ssl，或自定义的 certDir）；
目录内包含 cert.pem（证书）和 key.pem（私钥）；
根据系统将 cert.pem 添加到「受信任的根证书颁发机构」：
- macOS：双击 cert.pem → 「钥匙串访问」→ 右键证书 → 「显示简介」→ 「信任」→ 「使用此证书时」选择「始终信任」；
- Windows：右键 cert.pem → 「安装证书」→ 「本地计算机」→ 「将所有证书放入下列存储」→ 「受信任的根证书颁发机构」→ 完成。