前端工程化 / 系统课时
设置构建目标与兼容范围
设置构建目标与兼容范围
本课解决“代码能构建却不能在目标浏览器运行”的问题。你将把支持范围转成明确的 build.target,区分语法转换与运行时 Polyfill,并建立可验证、可持续调整的浏览器基线。
学习目标
- 根据产品数据和组织策略确定最低浏览器版本
- 正确配置
build.target,理解它能转换哪些内容 - 通过构建与真机测试验证兼容范围,而不是只看编译成功
先确定浏览器基线
不要先写 target 再猜它代表谁。应先收集线上访问数据、客户合同、内网设备版本和第三方容器限制,形成一份可审核的最低版本清单。公开站点通常以真实访问占比为主,企业后台还要考虑受管设备升级周期。
基线要写成浏览器版本,而不是“支持现代浏览器”这类模糊表述。每次降低目标都会增加转换工作、包体积或测试成本;每次提高目标都可能淘汰仍在使用的环境,因此应由产品、研发和测试共同确认。
配置 build.target
下面把最低兼容范围固定在配置中。数组表示构建结果必须同时满足这些目标,版本仅作示例,实际项目应替换为刚刚确认的基线。
import { defineConfig } from 'vite'
export default defineConfig({
build: {
// 显式固定基线,避免升级 Vite 后无意跟随默认值变化
target: ['chrome100', 'edge100', 'firefox100', 'safari15'],
},
})该配置会让构建器在安全范围内转换较新的 JavaScript 语法,并按目标环境生成生产代码。它不会自动证明业务依赖、第三方 SDK 和运行时 API 都兼容,验证仍需覆盖真实浏览器。运行生产构建:
npm run build预期输出:
vite v<VERSION> building for production...
✓ <COUNT> modules transformed.
dist/index.html <SIZE>
dist/assets/index-<HASH>.js <SIZE>
✓ built in <TIME>版本、模块数、文件哈希、体积和耗时会随项目变化;关键是构建成功且没有“无法安全转换目标语法”之类的错误。
理解语法转换与 Polyfill 边界

build.target 主要处理语法层面的降级,例如把目标环境不支持的新语法改写为较旧写法。它不会自动注入所有 Web API 或 ECMAScript 内建对象的实现,所以“代码里没有新语法”不等于“运行时一定不缺方法”。
例如,可选链可能被转换,但 structuredClone、某些 Intl 能力或较新的数组方法仍取决于浏览器本身。遇到这类缺口,应优先评估替代实现;确实需要时再按需引入 Polyfill,避免把整套兼容代码无差别塞进所有用户的包中。
若必须支持不具备现代 ESM 能力的旧浏览器,应评估官方 @vitejs/plugin-legacy。它解决的是另一层兼容问题,会生成兼容版代码与相应 Polyfill;启用前要重新评估包体积、双份产物和测试矩阵。
建立验证闭环
先在持续集成中执行生产构建,再用目标浏览器最低版本打开构建产物,覆盖首屏、路由切换、动态导入、登录、文件上传等关键路径。只运行开发服务器不足以验证,因为开发模式与生产转换链并不相同。
排查兼容故障时按顺序确认:报错属于解析失败还是运行时缺少 API;实际加载的是不是最新构建;第三方依赖是否声明了更高环境要求;Polyfill 是否在业务代码执行前加载。这样可以避免把所有问题都误归因于 target。