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

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

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

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

  • `@vitejs/plugin-basic-ssl`\] 插件的使用;

  • 使用 ipconfig /flushdns 等命令刷新 DNS;
  • 关于本地 HTTPS 证书的问题与建议。

为什么必须启用 HTTPS?

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

  • Notification.requestPermission()(Safari iOS 要求 PWA + HTTPS);
  • navigator.serviceWorker.register()(仅 HTTPS 生效);
  • Push APIWebAuthnClipboard
  • Chrome、Edge、Safari 近期都屏蔽了非安全源下的敏感 API;
  • 跨源请求中带 cookie 的接口(credentials: 'include')也要求 HTTPS。

总之:想不被浏览器"怼",就得上 HTTPS


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

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

安装插件

sql 复制代码
pnpm add -D @vitejs/plugin-basic-ssl

bash 复制代码
npm install -D @vitejs/plugin-basic-ssl

修改 vite.config.ts(或 nuxt.config.ts 中的 vite.plugins

javascript 复制代码
// 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
  }
}

或者自定义配置

ts 复制代码
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

示例:

vbnet 复制代码
127.0.0.1   vite.custom.com

刷新 DNS 缓存(防止浏览器缓存旧地址)

Windows

bash 复制代码
ipconfig /flushdns

macOS

ini 复制代码
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

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


关于本地 HTTPS 证书信任问题

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

解决方法(可选):

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

最终访问效果

vbnet 复制代码
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, .wowd等,google则会强制启用了 HSTS(HTTP Strict Transport Security)缓存强制使用 HTTPS 且不允许跳过证书错误,则会完全无法使用,建议避开这些。

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

小结

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

参考文档

相关推荐
brzhang22 分钟前
AI Agent 干不好活,不是它笨,告诉你一个残忍的现实,是你给他的工具太难用了
前端·后端·架构
brzhang27 分钟前
一文说明白为什么现在 AI Agent 都把重点放在上下文工程(context engineering)上?
前端·后端·架构
reembarkation37 分钟前
自定义分页控件,只显示当前页码的前后N页
开发语言·前端·javascript
gerrgwg1 小时前
React Hooks入门
前端·javascript·react.js
ObjectX前端实验室1 小时前
【react18原理探究实践】调度机制之注册任务
前端·react.js
汉字萌萌哒1 小时前
【 HTML基础知识】
前端·javascript·windows
ObjectX前端实验室2 小时前
【React 原理探究实践】root.render 干了啥?——深入 render 函数
前端·react.js
北城以北88883 小时前
Vue--Vue基础(二)
前端·javascript·vue.js
ObjectX前端实验室4 小时前
【react18原理探究实践】更新调度的完整流程
前端·react.js
tanxiaomi5 小时前
通过HTML演示JVM的垃圾回收-新生代与老年代
前端·jvm·html