从 father v2 升级到 father 4 完全指南

从 father v2 升级到 father 4 完全指南

father NPM package development tool 项目地址: https://gitcode.com/gh_mirrors/fath/father

前言

作为 umijs/father 项目的技术专家，我将为大家详细解析从 father v2（或 father-build v1）升级到 father 4 的全过程。father 4 带来了全新的构建理念和架构设计，理解这些变化对于顺利完成升级至关重要。

升级前的准备工作

在开始升级前，建议开发者：

1. 备份当前项目代码
2. 确保项目中的测试用例完整
3. 记录当前构建产物的结构和特性

核心架构变更

father 4 进行了重大的架构调整，主要体现在以下几个方面：

1. 构建模式重构：彻底放弃了 Rollup 构建模式，转而采用更现代的 Webpack（UMD）和 Babel/esbuild（Bundless）组合方案
2. 关注点分离：将文档、测试等非核心功能剥离，专注于构建本身
3. 简化配置：移除了大量冗余配置项，使配置更加清晰

详细升级步骤

第一步：依赖更新

首先需要更新 package.json 中的依赖：

{
  "scripts": {
+   "dev": "father dev",
    "build": "father build"
  },
  "devDependencies": {
-   "father": "^2.0.0"
+   "father": "^4.0.0"
  }
}

第二步：配置文件升级

建议将配置文件从 .fatherrc.js 迁移到 .fatherrc.ts，以获得更好的类型提示：

import { defineConfig } from 'father';

export default defineConfig({
  // 新配置项
});

第三步：构建模式调整

father 4 提供了两种主要构建模式：

1. Bundless 模式（默认）：基于 Babel/esbuild，适合输出 ESModule 和 CommonJS 格式
2. UMD 模式：基于 Webpack，适合需要打包的场景

Bundless 模式配置示例

export default defineConfig({
  esm: {
    output: 'es',  // 输出目录
    transformer: 'babel'  // 使用 babel 转换
  },
  cjs: {
    output: 'lib',  // 输出目录
    platform: 'browser',  // 目标平台
    transformer: 'esbuild'  // 使用 esbuild 转换
  }
});

UMD 模式配置示例

export default defineConfig({
  umd: {
    name: 'yourLibName',  // 全局变量名
    output: 'dist',  // 输出目录
    externals: {  // 外部依赖
      react: 'React',
      'react-dom': 'ReactDOM'
    }
  }
});

重要变更详解

1. CSS 处理策略变更

father 4 不再内置 CSS Modules 支持，这是出于以下考虑：

• 组件库使用 CSS Modules 会导致用户难以覆写样式
• 增加了用户项目的编译负担
• 现代前端项目通常有更好的 CSS 处理方案

解决方案：

• 对于样式表，建议使用普通 CSS 或 CSS-in-JS 方案
• 如果需要主题定制能力，可以考虑使用 UMD 构建

2. 文档功能迁移

father 4 移除了内置的文档功能，建议：

• 原有 Docz 用户迁移到 dumi
• 新项目直接使用 dumi 脚手架初始化

3. Monorepo 支持调整

father 4 不再内置 monorepo 支持，而是推荐：

• 结合 pnpm workspace 等方案
• 每个子项目独立配置 father

配置项变更对照表

| v2 配置项 | v4 替代方案 | 说明 | |----------|------------|------| | cjs.file | 移除 | Bundless 模式自动处理输出 | | esm.mjs | 移除 | 后续会提供更简单的方案 | | cssModules | 移除 | 不再支持 CSS Modules | | runtimeHelpers | 自动检测 | 根据 @babel/runtime 自动判断 | | extraRollupPlugins | 移除 | Rollup 相关配置不再支持 |

常见问题解决方案

1. 如何处理原有 Rollup 构建？

如果项目之前依赖 Rollup 的特定功能：

1. 评估是否可以改用 Bundless 模式
2. 必须打包时使用 UMD 模式
3. 复杂场景考虑自定义 Webpack 配置

2. 样式文件如何处理？

推荐方案：

1. 将样式文件作为独立资源发布
2. 让用户项目自行处理样式编译
3. 或者使用 CSS-in-JS 方案

3. 如何保持原有目录结构？

通过 output 配置项可以自定义输出目录：

export default defineConfig({
  esm: { output: 'es' },
  cjs: { output: 'lib' }
});

升级验证策略

产物对比法

1. 备份 v2 构建产物
2. 使用 v4 构建
3. 使用 diff 工具对比产物差异
4. 重点关注：
   • 模块导入/导出方式
   • 辅助函数引入
   • 第三方依赖处理

功能测试法

1. 在测试项目中安装新构建的包
2. 执行完整的功能测试
3. 特别注意：
   • 样式应用
   • 动态导入
   • 第三方依赖交互

最佳实践建议

1. 渐进式升级：对于复杂项目，可以分模块逐步升级
2. 利用类型提示：使用 TypeScript 配置文件获得更好的开发体验
3. 关注构建性能：father 4 的 esbuild 转换通常比 babel 更快
4. 合理选择模式：简单库用 Bundless，复杂库用 UMD

结语

father 4 的升级虽然带来了一些破坏性变更，但这些变化都是为了更好的构建体验和更现代化的架构。通过本文的指导，开发者应该能够顺利完成升级，并享受到新版本带来的性能提升和配置简化。如果在升级过程中遇到特殊问题，建议查阅最新的官方文档或寻求社区支持。

father NPM package development tool 项目地址: https://gitcode.com/gh_mirrors/fath/father