Vite 怎样设置 Baseline 浏览器构建目标

Vite 的 Baseline 构建目标通过 build.target: 'baseline-widely-available' 设置。它选择的是该 Vite 大版本固定日期对应的一组浏览器，而不是“今天所有浏览器”，也不会自动补齐全部 JavaScript API 和 CSS 能力。需要长期冻结支持范围时，可以改写成明确的浏览器版本数组；不要把日期字符串直接作为 target。

官方地址：https://vite.dev/

下面以 Vite 8 的客户端生产构建为例，把“用户能打开页面、能操作组件、能完成任务”分别落实到配置与降级设计。配置片段应合并进现有文件，保留项目原来的框架插件；示例用于解释写法，不代表已在读者设备或本文环境中实测。

先把用户设备范围写清楚

假设团队维护一个资料检索页面，核心任务是输入关键词、查看结果和展开筛选条件。兼容承诺不能只写“现代浏览器”，至少应列出桌面浏览器、iOS Safari，以及业务是否包含固定版本的内嵌 WebView。

建议在项目文档记录三件事：最低版本、必需任务、增强效果。即使高级布局或动画不可用，搜索与筛选也应该可操作。某个 WebView 的宿主 App 已升级，不等于其浏览器内核一定与桌面 Chrome 同步；有特殊设备时，应单独明确支持范围，而不是凭品牌名称套用 Baseline。

Baseline 的 Newly available 表示特性已在核心浏览器集合中互通，Widely available 则还经过了 30 个月。这个信号帮助团队选定共同基准，但不是对所有旧设备、所有嵌入环境和每个业务组件的保证。web.dev 的 Baseline 说明给出了两种状态的定义。

用固定的大版本基准设置 build.target

在现有 vite.config.ts 中明确保留默认策略，能让支持范围进入代码评审：

import { defineConfig } from 'vite'

export default defineConfig({
  // 合并到原配置中，已有框架插件和路径配置应继续保留。
  build: {
    // 采用当前 Vite 大版本固定的 Widely Available 基准。
    target: 'baseline-widely-available',
  },
})

Vite 8 官方构建选项对应的日期是 2026-01-01，映射为 chrome111、edge111、firefox114、safari16.4 和 ios16.4。这里的日期是基准计算时点，不是浏览器必须在当天发布，也不是某个 ECMAScript 年份。

固定日期意味着同一个大版本的默认策略不是每天随日历滚动。升级大版本仍要查看迁移说明：Vite 7 到 Vite 8 的默认范围就发生了变化。团队想跟随默认策略，仍需锁定工具链依赖，并记录升级带来的浏览器最低版本变化。Vite 构建选项与Vite 8 迁移说明分别说明配置语义和版本变化。

需要冻结范围时改用显式浏览器列表

如果团队希望升级 Vite 时先维持既有浏览器范围，可以把经过业务确认的列表写明。下面刻意使用与上面 Vite 8 基准相同的集合，方便比较；数组不是通用推荐，真正需要支持更旧设备时，应替换成项目承诺的版本并处理额外限制。

import { defineConfig } from 'vite'

// 这是项目的明确版本承诺，不依赖未来 Vite 默认基准如何调整。
const supportedBrowsers = [
  'chrome111',
  'edge111',
  'firefox114',
  'safari16.4',
  'ios16.4',
]

export default defineConfig({
  build: {
    // 多个浏览器共同约束语法转换，而不是输出五份按浏览器分发的包。
    target: supportedBrowsers,
  },
})

不要把 '2026-01-01' 或 Browserslist 查询语句直接填入这个字段。target 接受文档支持的特殊值、语言版本或浏览器版本，日期需要先映射成有效的目标列表。确实有自定义日期需求时，可通过 WebDX 维护的 baseline-browser-mapping 的 widelyAvailableOnDate 取得浏览器集合，再按构建器的命名规则处理；不要假定工具返回对象能不经转换直接传给 Vite。映射工具官方仓库说明了固定日期的接口。

核对配置时，应能回答“这几个版本从哪里来、谁负责调整、何时允许提高最低版本”。esnext 不是“更兼容”，而是尽量少做语法转换；es2015 这样的语言目标也不能替代完整的浏览器和 Web API 支持清单。

组件必须区分语法转换和能力降级

build.target 管的是最终构建包的兼容性目标，不能替浏览器实现缺失的 Web API。生产构建也不能被开发服务器里“看起来正常”的表现代替。Vite 的生产构建说明明确区分语法转换与通常不自动覆盖的 polyfill；其模块加载本身还有原生模块相关的最低要求，不能仅靠把 target 一直调低来消除这些要求。

对筛选组件，可以先让基本交互只依赖基础按钮和隐藏面板，而不是把可用性押在某个较新的弹层 API 上。下例没有接入新 API，也没有宣称补齐其行为，只展示一种降低必需依赖的组件设计：

筛选条件

在 Vite 项目的 HTML 入口中使用该示例时，读者应关注按钮是否可用键盘触发、展开状态是否同步、隐藏内容是否确实不占用交互空间。若没有 JavaScript 也必须能搜索，应把关键表单默认呈现并采用渐进增强，不能把以上默认隐藏方案当作无脚本降级。

如果换成其他原生 API 或第三方组件，需要另外确认该 API 的浏览器支持、必要的能力检测、替代界面和依赖库要求。改变构建目标不会自动替你设计这些分支。

把 CSS 和包体代价单独考虑

JavaScript 能解析不等于布局和颜色都能正常呈现。build.cssTarget 默认跟随 build.target，可在有明确需要时单独设定 CSS 压缩目标；它不是所有 CSS 新特性的全能替代器。不要为了一个未经确认的 WebView 问题就随意指定某个旧 Chrome 版本。

组件可以先提供简单布局，再以支持条件增强。下面的纵向列表是基础样式，Grid 只负责增强排列，不决定内容能否被访问：

/* 基础布局先保证内容按顺序呈现，不把新布局作为唯一可用方式。 */
.result-list {
  display: block;
}
.result-item {
  margin-block: 0.75rem;
}

/* 仅在浏览器声明支持 Grid 时增强布局，业务内容仍使用原有 HTML。 */
@supports (display: grid) {
  .result-list {
    display: grid;
    grid-template-columns: repeat(2, minmax(0, 1fr));
    gap: 1rem;
  }
  .result-item {
    margin-block: 0;
  }
}

MDN 的 @supports 说明介绍了条件样式的用途。这种条件不能替代对浏览器实际渲染问题的判断，也不等于自动为不支持的属性生成 polyfill。

更低的语法目标可能需要更多转换；额外 polyfill 或兼容插件也可能改变资源成本。应比较相同依赖与配置下的产物大小、加载请求和真实交互体验，而不是直接宣称“调成 esnext 一定更快”。这里不提供虚构的体积百分比或性能测试结果。

升级时保留一张兼容决策表

构建后，应在项目自己的发布流程里确认必需任务、键盘操作、目标设备和错误状态；本文没有执行这些设备测试。如果升级后兼容性承诺无法满足，应恢复已确认可用的依赖锁文件和配置组合，而不是只把一项 target 改回去就宣布回退完成。

为什么配置相同，升级 Vite 后目标变了？

特殊值代表当前大版本的默认基准。要避免默认策略变化影响项目承诺，记录明确的浏览器列表，再根据业务计划调整。

是不是所有 Baseline 特性都自动转译？

不是。Baseline 是兼容性信号；语法转换、API 补充和交互降级属于不同工作，CSS 的支持也需要单独考虑。

只写 Browserslist 就够了吗？

不要假定其配置会自动驱动 Vite 的 build.target。本文直接在 Vite 配置中声明目标，若项目另有适配插件，应把映射规则和插件版本一并记录。

选定日期只是开始。真正可维护的做法，是把浏览器列表、组件基础任务和增强能力写成同一个支持承诺，并在工具链升级时有意识地更新它。