笔记 · 踩坑记录

依赖升级踩坑记:Vite 与 Node 版本的那点事

一次例行依赖升级,本地跑得好好的,推到流水线就报模块解析失败。排查半天,问题不在 Vite 本身,而在 Node 版本。

现象

本地 Node 20 构建正常,CI 上的镜像还是 Node 18,报的是同一个包「找不到导出」。这类报错看着像依赖装错了,实际是运行时对 package.json 里 exports 字段的解析规则不同。

原因

新版本工具链开始使用较新的条件导出写法,低版本 Node 认不出来,于是回退到旧入口,找不到就抛错。构建工具升级时,Node 版本这条线必须一起看。

怎么避免

  • 在 package.json 里写明 engines,让安装阶段就拦住不匹配的版本
  • 把 CI 镜像的 Node 版本和本地对齐,别让环境成为变量
  • 升级构建工具前,先看它的 peer 依赖要求的 Node 下限

评论13

访客

登录后参与评论,你的发言会署上自己的名字。

  • 周迟

    周迟作者@zhouchi2026-09-22

    自己先补一句 —— 文中那几处踩坑的细节,备注里写得更全,需要的话我再展开。

  • 江辰

    江辰@jiangchen2026-09-24

    缓存那部分能不能再展开讲讲?我们这边命中率一直上不去。

  • 唐棠

    唐棠@tangtang2026-09-25

    产物裁剪这条被低估了,sourcemap 和语言包占的空间比想象中大。

  • 孟凡

    孟凡@mengfan2026-09-26

    构建脚本重写那段看着很有共鸣,最花时间的果然还是新旧产物对照。

  • 邓可

    邓可@dengke2026-09-27

    把流水线耗时先打出来这一步太重要了,不然优化全靠猜。

  • 罗叙

    罗叙@luoxu2026-09-28

    同意,先有数据再谈优化,不然改了半天不知道有没有用。