Vite 本地 HTTPS 配置

问题描述

在本地开发环境中使用 Vite 时，配置 HTTPS 会遇到 Chrome 浏览器显示证书无效的问题。即使按照官方文档配置了证书文件，浏览器仍然会提示安全警告。

典型的配置如下：

import { defineConfig  } from 'vite'
import vue from '@vitejs/plugin-vue'
import fs from 'fs';

export default defineConfig({
  resolve: { alias: { '@': '/src' } },
  plugins: [vue()],
  https: {
    key: fs.readFileSync('RootCA-key.pem'),
    cert: fs.readFileSync('RootCA.pem')
  }
})

虽然使用 npm run dev -- --https 命令可以启动 HTTPS 服务器，但浏览器会显示证书无效的警告。

解决方案

方案一：使用 vite-plugin-mkcert（推荐）

方案二：使用 @vitejs/plugin-basic-ssl

Vite 官方提供的简化方案：

bash

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

配置示例：

import basicSsl from '@vitejs/plugin-basic-ssl'

export default {
  plugins: [
    basicSsl()
  ],
  server: {
    https: true
  }
}

注意

此方案仅适用于开发环境，生产环境需要使用真实的证书（如 Let's Encrypt）

方案三：手动配置 mkcert 证书

如果需要更多控制，可以手动使用 mkcert：

安装 mkcert：

bash

# macOS
brew install mkcert

# Windows (使用 Chocolatey)
choco install mkcert

# Linux
sudo apt install libnss3-tools
wget -O mkcert https://github.com/FiloSottile/mkcert/releases/download/v1.4.4/mkcert-v1.4.4-linux-amd64
chmod +x mkcert
sudo mv mkcert /usr/local/bin/

安装根证书：

bash

mkcert -install

为项目生成证书：

bash

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

配置 Vite：

import { defineConfig } from 'vite'
import fs from 'fs'

export default defineConfig({
  server: {
    https: {
      key: fs.readFileSync('./.cert/key.pem'),
      cert: fs.readFileSync('./.cert/cert.pem'),
    },
  },
})

方案四：跨设备测试配置

如果需要在不同设备（如手机）上测试本地开发环境：

import { defineConfig } from 'vite'
import mkcert from 'vite-plugin-mkcert'

export default defineConfig({
  server: {
    https: true,
    host: '0.0.0.0' // 允许网络访问
  },
  plugins: [mkcert()]
})

然后在移动设备上安装根证书（位于 mkcert -CAROOT 命令显示的路径中）。

移动设备证书安装指南

Android：设置 → 安全 → 加密与凭据 → 安装证书 → CA证书
iOS：下载根证书后，前往设置 → 已下载描述文件 → 安装

常见问题解答

为什么需要 HTTPS 本地开发？

现代浏览器许多功能（如 Service Workers、地理定位等）要求使用安全上下文，HTTPS 是必要条件。

Q：证书仍然不被信任怎么办？ A：确保已正确运行 mkcert -install，并重启浏览器。

Q：如何在 Docker 中使用？ A：在 Docker 容器内同样安装 mkcert，或挂载已生成的证书文件。

Q：生产环境如何处理？ A：生产环境应使用 Let's Encrypt 等可信证书颁发机构签发的证书，或通过反向代理（如 Nginx）处理 HTTPS。

总结

使用 vite-plugin-mkcert 是最简单可靠的本地 HTTPS 解决方案，它自动化了证书生成和信任过程。对于需要更多控制的情况，可以手动使用 mkcert 工具。无论选择哪种方案，都应避免在生产环境使用自签名证书。

相关文章

Vite 本地 HTTPS 配置 ​

问题描述 ​

解决方案 ​

方案一：使用 vite-plugin-mkcert（推荐） ​

方案二：使用 @vitejs/plugin-basic-ssl ​

方案三：手动配置 mkcert 证书 ​

方案四：跨设备测试配置 ​

常见问题解答 ​

总结 ​

Vite 本地 HTTPS 配置

问题描述

解决方案

方案一：使用 vite-plugin-mkcert（推荐）

方案二：使用 @vitejs/plugin-basic-ssl

方案三：手动配置 mkcert 证书

方案四：跨设备测试配置

常见问题解答

总结