如何在本地开发环境中配置 HTTPS本文介绍了如何通过修改 Hosts 文件与 mkcert 工具，在本地快速搭建受信任

🛠️ 如何在本地开发环境中配置 HTTPS

在现代前端开发中，本地环境早已不再只是简单的页面渲染调试场。为了精准模拟生产环境或调试特定功能（如地理位置定位、HTTP/2、PWA 等），我们往往需要配置 HTTPS。

但现实情况是，现代浏览器对安全上下文的管控越来越严格。普通的 HTTP 本地服务不仅会在地址栏留下刺眼的“不安全”警告，还会直接导致部分高级 Web API 失效，甚至在请求线上 HTTPS 接口时频繁触发“混合内容（Mixed Content）”拦截。

为了彻底解决这些开发痛点，本文整理了通过修改 Hosts 文件和使用 mkcert 工具，在本地快速搭建受信任、无警告的 HTTPS 开发环境的实战步骤，让你的本地调试体验真正与线上保持一致。

1. 修改本地 Hosts 文件

首先，我们需要将自定义域名指向本地回环地址（127.0.0.1）。

📂 文件位置

不同操作系统的 hosts 文件路径如下：

Windows: C:\Windows\System32\drivers\etc\hosts
macOS / Linux: /etc/hosts

💻 Windows 系统操作指南

由于修改系统文件需要管理员权限，请以管理员身份运行编辑器：

点击「开始」菜单，搜索 记事本。
右键点击记事本图标，选择 「以管理员身份运行」。
在记事本中点击「文件」→「打开」。
在地址栏输入路径：C:\Windows\System32\drivers\etc\ 并回车。
注意：右下角文件类型需选择 「所有文件 (.)」，否则看不到 hosts 文件。
选中 hosts 文件并打开，在文件末尾添加你的域名映射：

# 格式：IP地址 域名
127.0.0.1       localhost
127.0.0.1       xxx.com  # 这里填入你要代理的自定义域名

保存文件 (Ctrl + S)。

2. 使用 mkcert 生成本地 HTTPS 证书

mkcert 是一个简单的工具，用于在本地创建受信任的 HTTPS 证书。

📥 安装与配置 (Windows)

下载工具：下载 mkcert 的 .exe 文件。
安装根证书授权机构 (CA)：打开命令行窗口（CMD 或 PowerShell），运行以下命令以生成本地 CA 并将其安装到系统信任列表中：
```
mkcert -install
```
说明：此步骤生成的本地 CA 仅在你的设备上受信任，用于消除浏览器的"不安全"警告。

📜 生成证书

你可以选择在任意目录生成证书，或者直接在项目目录中生成。

为 localhost 生成证书：
```
mkcert localhost
```
为自定义域名（如 mysite.example）生成证书：
```
mkcert mysite.example
```

运行后，当前目录下会生成 .pem 格式的密钥文件（key）和证书文件（cert）。

3. 在项目代码中配置 HTTPS

拿到证书后，需要在开发服务器配置中启用 HTTPS。以下以 rsbuild 或 vite 为例。

基础配置

在配置文件（如 rsbuild.config.ts 或 vite.config.ts）中读取证书文件：

import { defineConfig } from 'vite'; // 或 rsbuild 对应的 defineConfig
import fs from 'fs';

export default defineConfig({
  server: {
    https: {
      // 请替换为你实际生成的证书路径
      key: fs.readFileSync('./path/to/localhost-key.pem'),
      cert: fs.readFileSync('./path/to/localhost.pem'),
    }
  }
})

4. 团队协作最佳实践 (自动化脚本)

如果你的项目是多人协作开发，为了避免每个人都手动安装 mkcert 和生成证书，可以将工具和脚本集成到项目中。

📂 项目结构调整

将 mkcert.exe 放入项目根目录下的 cert 文件夹中。

⚙️ 配置文件 (`config.ts`)

使用 path.resolve 确保路径在不同环境下都能正确解析：

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

export default defineConfig({
  server: {
    host: 'localhost',
    https: {
      // 自动读取项目根目录下 cert 文件夹中的证书
      key: fs.readFileSync(path.resolve(__dirname, './cert/key.pem')),
      cert: fs.readFileSync(path.resolve(__dirname, './cert/cert.pem')),
    },
  },
});

🚀 添加执行脚本 (`package.json`)

在 package.json 中添加一个脚本，一键完成证书安装和生成：

{
  "scripts": {
    "setup:cert": "cd cert && mkcert.exe -install && mkcert.exe localhost"
  }
}

使用方法：

新成员拉取代码后，只需运行以下命令即可自动配置好本地 HTTPS 环境：

npm run setup:cert
# 或者
yarn setup:cert

如何在本地开发环境中配置 HTTPS