构建系统

目的与范围

本文档详细解释了 Apache ECharts 的构建系统，该系统负责编译、打包和准备库以供分发。构建系统将 TypeScript 和 JavaScript 源代码转换为各种分发格式，处理代码优化，并生成类型定义。有关测试框架的信息，请参阅测试框架。

概述

ECharts 构建系统旨在生成多种分发格式，以支持不同的用户需求，从功能齐全的打包版本到轻量级版本。它利用 TypeScript 编译、Rollup 打包和自定义代码转换来创建生产就绪的输出。

来源：build/build.js build/pre-publish.js build/config.js tsconfig.json

关键组件

构建系统由几个关键文件组成

文件	描述
`build/build.js`	主构建脚本，处理命令行参数并协调构建过程
`build/config.js`	配置文件，定义如何创建不同的打包版本
`build/pre-publish.js`	处理 TypeScript 编译和 npm 发布准备
`tsconfig.json`	TypeScript 编译器配置

来源：build/build.js build/config.js build/pre-publish.js tsconfig.json

构建流程

构建过程遵循特定的流程，具体取决于它是常规构建还是预发布操作。

来源：build/build.js30-235

命令行参数

构建脚本接受多个命令行参数以自定义构建过程

参数	描述
`--prepublish`	构建发布到 npm 所需的所有文件
`--min`	压缩输出文件并移除错误日志打印代码
`--type <type>`	指定构建类型：“simple”、“common”、“all”或逗号分隔的列表
`--format <format>`	指定输出格式：“umd”、“amd”、“iife”、“cjs”、“esm”

来源：build/build.js42-78

构建类型

ECharts 提供不同的构建类型以适应各种使用场景

构建类型	描述	输出文件
`all`	包含所有图表和组件的完整版本	`dist/echarts.js`
`common`	包含常用图表的通用版本	`dist/echarts.common.js`
`simple`	包含基本图表的轻量级版本	`dist/echarts.simple.js`
`blank`	仅包含核心功能的最小版本	`dist/echarts.blank.js`

来源：build/pre-publish.js111-114 .gitignore185-189

预发布过程

预发布过程通过执行多项任务来准备代码库以进行 npm 发布

来源：build/pre-publish.js176-208

TypeScript 编译

ECharts 代码库使用 TypeScript，需要编译为 JavaScript。TypeScript 编译器通过 tsconfig.json 进行配置。

来源：tsconfig.json build/pre-publish.js246-262

代码转换

在构建过程中，会应用某些代码转换

移除开发代码：移除仅用于开发的代码
导入路径转换：转换相对路径和模块引用
文件扩展名添加：确保文件扩展名正确指定

来源：build/pre-publish.js346-366 build/pre-publish.js307-334

输出结构

构建系统生成各种输出文件和目录

来源：.gitignore184-212 build/pre-publish.js378-436

构建扩展

构建系统还处理构建 BMap（百度地图）和 DataTool 等扩展

来源：build/build.js93-99 build/config.js121-161

模块格式

ECharts 支持不同的模块格式以适应各种开发环境

格式	描述	用例
UMD	通用模块定义	在浏览器、Node.js 和 AMD 加载器中工作
ESM	ECMAScript 模块	现代 JavaScript 环境，支持摇树优化（tree-shaking）
CJS	CommonJS	Node.js 环境
IIFE	立即执行函数表达式	直接用于浏览器
AMD	异步模块定义	RequireJS 和类似加载器

来源：build/config.js41-80 build/build.js117-128

构建示例

构建完整版本 (UMD)

以 UMD 格式构建 ECharts 的完整版本

node build/build.js --type all

这将生成 dist/echarts.js 和 dist/echarts.min.js。

构建通用版本（精简）

构建精简的通用版本

node build/build.js --type common --min

这将生成 dist/echarts.common.min.js。

构建 ESM 版本

node build/build.js --format esm

这将生成 dist/echarts.esm.js 和 dist/echarts.esm.mjs。

来源：build/build.js57-59 build/build.js117-128

预发布构建

预发布构建准备包以供 npm 发布

node build/build.js --prepublish

这将编译 TypeScript、转换代码、生成类型定义，并根据 .npmignore 中的配置设置 npm 包结构。

来源：build/build.js90-92 .npmignore

结论

ECharts 构建系统是一个全面的工具链，用于将源代码转换为各种分发格式。它支持多种构建类型、模块格式和扩展，以适应不同的使用场景，从简单的浏览器引入到支持摇树优化的现代 JavaScript 框架。