HTTPS：本地开发绕不开的设置指南本文项目托管在design-pattern-in-action 随着浏览器对安全策略

本文项目托管在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：

安装插件

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

或

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

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

// 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
  }
}

或者自定义配置

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`

示例：

127.0.0.1   vite.custom.com

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

Windows

ipconfig /flushdns

macOS

sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

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

关于本地 HTTPS 证书信任问题

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

解决方法（可选）：

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

最终访问效果

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` 或信任自签证书即可

参考文档

Vite 官方文档 · HTTPS 配置
@vitejs/plugin-basic-ssl
mkcert — 为本地生成可信证书的首选工具

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