构建系统和工具
OpenLayers 使用基于 npm scripts 和现代 JavaScript 工具的综合构建系统，将 TypeScript 源代码转换为可分发包。该系统处理转译、捆绑、类型生成、测试和开发工作流程自动化。
构建管线架构
构建管线通过 package.json 中定义的 npm 脚本，将源文件转换通过多个阶段。管线处理 TypeScript 编译、模块捆绑和包准备。
构建管线流程
核心构建脚本
构建系统使用协调文件操作、转译和捆绑的 npm 脚本：
| 脚本 | 命令 | 目的 |
|---|---|---|
| transpile | shx rm -rf build/ol && shx mkdir -p build/ol && shx cp -rf src/ol build && node tasks/serialize-workers.cjs && node tasks/set-version.js | 准备源文件，处理 workers，设置版本 |
| build-index | shx rm -f build/index.js && npm run transpile && node tasks/generate-index.js | 创建主模块入口点 |
| build-full | shx rm -rf build/full && npm run build-index && npx rollup --config config/rollup-full-build.js | 使用 Rollup 捆绑库 |
| copy-css | shx cp src/ol/ol.css build/ol/ol.css | 复制 CSS 样式表 |
| generate-types | tsc --project config/tsconfig-build.json --declaration --declarationMap --emitDeclarationOnly --outdir build/ol | 生成 TypeScript 声明 |
| build-package | npm run build-full && npm run copy-css && npm run generate-types && node tasks/prepare-package.js | 组装最终分发包 |
构建过程步骤
1. 转译 (transpile)
此初始步骤准备源文件以进行进一步处理：
- 清理
build/ol目录 - 创建必要的目录
- 将源文件从
src/ol复制到build - 通过
serialize-workers.cjs处理 web worker 文件 - 通过
set-version.js设置版本信息
2. 索引生成 (build-index)
此步骤创建主入口点：
- 删除任何现有的
build/index.js - 确保转译完成
- 使用
generate-index.js从转译的源生成索引文件
3. 完整构建 (build-full)
此步骤创建库的捆绑版本：
- 清理
build/full目录 - 确保生成索引
- 使用 Rollup 创建包含所有依赖项的捆绑版本
4. 类型生成 (generate-types)
此步骤创建 TypeScript 声明文件：
- 使用具有特定配置的 TypeScript 编译器
- 生成
.d.ts和.d.ts.map文件 - 输出到
build/ol目录
5. 包创建 (build-package)
此最后一步创建完整的分发包：
- 确保完整构建完成
- 将 CSS 文件复制到构建目录
- 确保生成类型声明
- 通过
prepare-package.js准备最终包以供分发
依赖管理
OpenLayers 仅使用五个生产依赖项维持最小的运行时占用空间，同时使用广泛的开发工具链进行构建、测试和开发。
运行时依赖
开发工具链依赖
| 类别 | 关键依赖 | 目的 |
|---|---|---|
| 构建工具 | rollup@^4.1.4, typescript@5.8.3, webpack@^5.27.2 | 模块捆绑和编译 |
| 测试 | karma@^6.3.8, mocha@11.7.1, puppeteer@24.16.1 | 浏览器和 Node.js 测试 |
| 代码质量 | eslint@^9.16.0, eslint-config-openlayers@^20.0.0 | Linting 和样式强制 |
| 文档 | jsdoc@4.0.4, metalsmith@^2.5.0, marked@16.1.2 | API 文档和示例 |
| 开发 | webpack-dev-server@^5.0.2, express@^5.1.0 | 开发服务器 |
测试基础设施
OpenLayers 实现了多层测试策略，涵盖代码质量、类型安全、单元测试、集成测试和视觉回归测试。
测试管线
Karma 浏览器测试配置
浏览器测试环境使用 Karma 与复杂的 webpack 集成：
测试类别
| 测试类型 | 运行器 | 配置 | 目的 |
|---|---|---|---|
| Linting | ESLint | eslint-config-openlayers | 代码样式和质量 |
| 类型检查 | TypeScript | tsconfig.json、config/tsconfig-strict.json | 类型安全 |
| 单元测试 | Karma + Mocha | test/browser/karma.config.cjs | 浏览器兼容性 |
| Node 测试 | Mocha | test/node/ | 服务器端功能 |
| 视觉测试 | 自定义 | test/rendering/ | 渲染准确性 |
开发工作流程
OpenLayers 为不同的开发场景提供专用 npm 脚本，从核心库开发到示例和文档。
开发服务器设置
核心开发工作流程
| 工作流程 | 命令 | 目的 |
|---|---|---|
| 库开发 | npm run transpile → npm test → npm run build-package | 核心库更改 |
| 示例开发 | npm start → 编辑 → 刷新浏览器 | 交互式示例 |
| API 文档 | npm run apidoc | 生成文档 |
| 完整发布构建 | npm run build-package | 分发准备 |
示例开发过程
示例系统为开发提供即时反馈：
- 启动开发服务器：
npm start启动具有热重新加载的webpack-dev-server - 实时开发：对示例代码的更改会自动刷新浏览器
- 生产构建：
npm run build-examples在build/examples/中创建优化的示例
构建输出
构建过程创建这些输出：
| 输出 | 位置 | 描述 |
|---|---|---|
| 转译源代码 | build/ol/ | 处理的源文件 |
| 索引文件 | build/index.js | 主入口点 |
| 完整构建 | build/full/ | 捆绑的库 |
| TypeScript 声明 | build/ol/*.d.ts | 类型定义 |
| CSS | build/ol/ol.css | 样式表 |
| 包 | build/ | 完整分发包 |
API 文档生成
OpenLayers 还包括用于生成 API 文档的脚本：
| 脚本 | 目的 |
|---|---|
| apidoc | 使用 JSDoc 生成 API 文档 |
| apidoc-debug | 生成启用调试的 API 文档 |
这些脚本使用 JSDoc 和自定义配置从源代码注释生成文档。
示例构建
示例系统有专用的构建脚本：
| 脚本 | 目的 |
|---|---|
| serve-examples | 启动用于示例的 webpack dev 服务器 |
| build-examples | 为生产构建示例 |
示例使用 webpack 进行捆绑和开发服务。