当前位置：首页 > news >正文

Vite 开发环境配置 HTTPS

news 2026/8/2 5:47:32

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→ 「安装证书」→ 「本地计算机」→ 「将所有证书放入下列存储」→ 「受信任的根证书颁发机构」→ 完成。