文章

HTTPS：本地开发绕不开的设置指南

发表于
作者 cbtpro
7 分钟阅读
HTTPS：本地开发绕不开的设置指南

本文项目托管在design-pattern-in-action

随着浏览器对安全策略的逐步收紧，启用本地 HTTPS 开发环境已成为前端开发的新常态。不论你是在开发 PWA、调用 Web API、集成通知权限，还是调试跨域接口，HTTPS 都是不可或缺的基本条件。

这篇文章将围绕以下四个核心点，手把手带你配置本地 HTTPS 开发环境：

  • [@vitejs/plugin-basic-ssl] 插件的使用；- hosts 文件设置自定义域名；- 使用 ipconfig /flushdns 等命令刷新 DNS；- 关于本地 HTTPS 证书的问题与建议。

    为什么必须启用 HTTPS？

浏览器中的某些功能必须在 HTTPS 下才能使用，包括但不限于：

  • Notification.requestPermission()（Safari iOS 要求 PWA + HTTPS）；- navigator.serviceWorker.register()（仅 HTTPS 生效）；- Push API、WebAuthn、Clipboard；- Chrome、Edge、Safari 近期都屏蔽了非安全源下的敏感 API；- 跨源请求中带 cookie 的接口（credentials: ‘include’）也要求 HTTPS。 总之：想不被浏览器“怼”，就得上 HTTPS。

使用 @vitejs/plugin-basic-ssl 启用 HTTPS

如果你正在使用 Vite 或基于 Vite 的 Nuxt 3、Vue 3 项目，你可以非常快速地启用本地 HTTPS：

安装插件

1

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

或

1

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

修改 vite.config.ts（或 nuxt.config.ts 中的 vite.plugins）

1
2
3
4
5
6
7
8
9
10
11
12

// vite.config.ts
import basicSsl from '@vitejs/plugin-basic-ssl'

export default {
  plugins: [basicSsl()],
  server: {
    https: true,
    // 支持 LAN 或自定义域名访问
    host: '0.0.0.0',
    port: 443
  }
}

或者自定义配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

import { defineConfig } from 'vite';
import basicSsl from '@vitejs/plugin-basic-ssl';

// https://vitejs.dev/config/
export default defineConfig({
  server: {
    https: true,
    host: '0.0.0.0',
    /**
     * 端口，如果配置了以配置的为准，否则以默使用或自增
     */
    // port: 443,
  },
  plugins: [
    basicSsl({
      /** 
       * 证书名称，不可以使用中文、韩文、特殊字符等，只允许使用英文字母和数字符号
       * 否则，服务器启动时报错，尝试删除缓存后，
       * 重新安装依赖`npm install`再启动服务即可解决
       */
      name: 'test',
      /*
       * 自定义证书支持的域名，支持数组通配符，
       * 如果配置'*'则表示匹配vite和所有域名和ip，
       * 修改配置，需要删除缓存证书，并重启服务
       */
      domains: [
        // '10.10.246.238',
        // '172.31.176.1',
        // 'localhost',
        'vite.custom.com',
        'vite',
        '*',
      ],
      /**
       * 自定义证书目录， 默认目录：./node_modules/.vite/basic-ssl
       */
      // certDir: './node_modules/.vite/basic-ssl',
    }),
  ],
});

这会自动生成本地自签名的 SSL 证书（在 node_modules/.vite-plugin-basic-ssl 中） 修改basicSsl配置需要删除证书缓存，并重启服务才能生效 证书名称不可以使用除英文数字、英文字符外的字符，否则启动时会报Error: error:0680009B:asn1 encoding routines::too long，生成的私钥字符串会多10个字符。解决方法是改回英文，删除证书、重新npm instal既可以解决。

配置本地自定义域名（修改 hosts 文件）(可选)

我们不希望每次都访问 https://localhost:443，而是能访问 https://vite.custom.com 这样更语义化的域名。

修改本地 hosts 文件

| 系统 | 路径 || — | — || Windows | C:\Windows\System32\drivers\etc\hosts || macOS/Linux | /etc/hosts |

示例：

1

127.0.0.1   vite.custom.com

刷新 DNS 缓存（防止浏览器缓存旧地址）

Windows

1

ipconfig /flushdns

macOS

1

sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

之后重启浏览器，或者在 Chrome 的 chrome://net-internals/#dns 中点击 Clear host cache。

关于本地 HTTPS 证书信任问题

启用 HTTPS 后，如果浏览器提示“不受信任”或“连接不安全”，是因为本地使用的是自签名证书，未被系统信任。

解决方法（可选）：

  • 使用 mkcert 为你的本地域名生成本地受信证书，并安装根证书；- 或在浏览器手动信任一次即可开发使用；- 部分插件（如 @vitejs/plugin-basic-ssl）已自动生成简单证书用于本地调试，无需生产级信任。

    最终访问效果

1

https://vite.custom.com:5173/

使用443端口

不使用443端口

可以正常获取浏览器权限

因为是自己签发的证书，不是浏览器认可的可信机构发布的证书，所以浏览器会故意显示不是私密链接，并折叠入口，需要手动点击显示详情，继续前往才可以访问。

而有些顶级域名域名，比如.dev、.app、.page, .day, .foo, .blog, .cloud, .docs, .drive, .family, .film, .fun, .fyi, .game, .home, .inc, .live, .lol, .mail, .map, .mba, .med, .mom, .music, .pet, .phd, .play, .plus, .search, .shop, .site, .tech, .tube, .vip, .web, .wow等，google则会强制启用了 HSTS（HTTP Strict Transport Security）缓存，强制使用 HTTPS 且不允许跳过证书错误,则会完全无法使用，建议避开这些。

  • 使用 HTTPS 加密；- 使用了系统级域名解析；- 支持浏览器通知、服务工作线程等高级功能；- 支持移动端内网访问（通过 IP + hosts 配合使用）。

    小结

| 步骤 | 工具 || — | — || 启用本地 HTTPS | @vitejs/plugin-basic-ssl || 自定义域名 → localhost | 修改 hosts 文件 || 避免 DNS 缓存问题 | ipconfig /flushdns（或 dscacheutil） || 浏览器证书警告 | 使用 mkcert 或信任自签证书即可 |

参考文档

前端 每天一个知识点 React.js HTTPS HarmonyOS Vite
本文由作者按照 CC BY 4.0 进行授权