Vite 开发环境配置 HTTPS

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.0Vite ≥ 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 -D3. 基本使用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 expose4. 高级配置插件支持传入可选配置项自定义证书相关行为4.1 配置项说明配置项类型默认值说明certDirstring~/.vite-plugin-ssl证书存储目录绝对路径 / 相对路径均可hostsstring[][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→ 「安装证书」→ 「本地计算机」→ 「将所有证书放入下列存储」→ 「受信任的根证书颁发机构」→ 完成。6. 常见问题Q1启动后仍显示 HTTP 地址检查插件是否正确注册到plugins数组中确认 Vite 版本 ≥ 2.0.0重启 Vite 开发服务器修改配置后需重启。Q2自定义 hosts 后访问提示证书无效确保hosts配置包含你访问的域名 / IP清除浏览器缓存或重启浏览器后重试重新生成证书删除证书目录如~/.vite-plugin-ssl重启开发服务器。Q3证书目录权限不足自定义certDir到项目内如./ssl避免系统目录权限问题给证书目录赋予读写权限如chmod 755 ./ssl。7. 注意事项该插件仅适用于本地开发环境生产环境需使用正规 CA 机构颁发的 SSL 证书如 Lets Encrypt自签名证书无法在生产环境使用仅用于开发调试若同时配置 Vite 的server.https选项插件会覆盖该配置的默认行为升级插件后若出现证书问题可删除旧证书目录重新生成。