前端工程化 / 系统课时

管理 SSR 依赖外部化

管理 SSR 依赖外部化

SSR 依赖既可以留给 Node.js 在运行时加载,也可以由 Vite 打进服务端产物。本课用 external、noExternal 和条件导出配置建立判断顺序,解决模块格式、入口选择与运行时缺包问题。

学习目标

  • 判断依赖应当外部化还是打入 SSR 产物
  • 正确组合 ssr.external、ssr.noExternal 与解析条件
  • 用开发、构建和运行三阶段验证配置是否一致

先理解两种处理方式

外部化表示服务端产物保留对依赖的导入,部署时再由 Node.js 从 node_modules 加载。这样构建更快、产物更小,适合原生模块、数据库驱动和明确支持当前 Node.js 模块格式的包。

不外部化表示依赖进入 Vite 的转换与打包流程。它适合发布格式不规范、需要读取特定条件导出、包含需要转换的源码,或开发环境正常而构建后出现 ESM、CommonJS 互操作错误的依赖。

SSR 依赖外部化决策流程

配置精确名单

默认情况下,普通依赖会被外部化,工作区链接依赖通常为了热更新而不外部化。不要一开始就设置 noExternal: true,应先把出现问题的包缩小到精确名单。

下面是片段示例,假定 pg 保持运行时加载,而 @acme/shared-ui 需要经过 Vite 转换。包名应替换为项目中的真实依赖。

ts
import { defineConfig } from 'vite'

export default defineConfig({
  ssr: {
    external: ['pg'],
    noExternal: ['@acme/shared-ui'],
  },
})

生效行为:SSR 构建会保留对 pg 的外部导入,并把 @acme/shared-ui 及其代码纳入服务端构建。若同一个包同时出现在两个字符串名单中,显式 external 名单优先;若同时设置 external: true 与 noExternal: true,则 noExternal: true 优先,不再外部化依赖。

处理条件导出

包的 exports 可能同时声明 node、import、require 或自定义条件。非外部化依赖由 Vite 解析,可通过 ssr.resolve.conditions 调整;外部化依赖在 SSR 导入阶段使用 ssr.resolve.externalConditions,运行 Node.js 时还要传入相同的自定义条件,否则开发与生产可能选中不同入口。

ts
import { defineConfig } from 'vite'

export default defineConfig({
  ssr: {
    noExternal: ['@acme/shared-ui'],
    resolve: {
      conditions: ['module', 'node', 'development|production', 'custom'],
      externalConditions: ['node', 'module-sync', 'custom'],
    },
  },
})

验证自定义条件时,在开发和生产运行命令中保持同一组 Node.js 条件。

bash
NODE_OPTIONS="--conditions custom" npm run dev
NODE_OPTIONS="--conditions custom" node <PATH>/server.js

预期结果

text
开发环境与生产运行时选择相同的 custom 条件入口;实际端口、路径和启动日志可能不同。

按现象定位根因

出现 ERR_REQUIRE_ESM、默认导入值异常或包内部源码未转换时,先把该包加入 noExternal。出现原生二进制未找到、数据库驱动被错误打包或部署产物缺少运行时依赖时,检查是否应加入 external,并确认生产环境安装了对应依赖。

如果只有构建后失败,比较开发启动与生产启动使用的 Node.js 版本、NODE_OPTIONS 和包管理器锁文件。不要用全量 noExternal: true 掩盖问题,它会扩大产物并可能把不适合打包的 Node.js 依赖带入构建。

验收配置

先运行 SSR 开发模式确认首屏渲染,再执行生产构建并用真实 Node.js 入口启动。最后访问一个会触发目标依赖的页面或接口,确认没有模块格式、条件导出和运行时缺包错误。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

管理 SSR 依赖外部化

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通