企业官网建设流程全解析

Apache DolphinScheduler 全新 Web UI（dolphinscheduler-ui）开发与构建实战指南

【免费下载链接】dolphinschedulerApache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code项目地址: https://gitcode.com/GitHub_Trending/dol/dolphinscheduler

本篇指南围绕 Apache DolphinScheduler 仓库中dolphinscheduler-ui模块的 README 展开，系统讲解这套自 V3.0.0-Release 起全新重写的 Web 前端管理系统的技术栈、本地开发启动、生产构建打包，以及参与前端开发时的代码规范与类型检查流程。读完本文，你将能够独立完成该 UI 模块的环境准备、环境变量配置、开发调试与产物构建，并理解其与后端dolphinscheduler-api的对接原理。

全新 UI：一次彻底的前端重构

dolphinscheduler-ui是 Apache DolphinScheduler 的全新一代前端管理系统（V3.0.0-Release 引入）。相对于旧版 UI，它并非简单改版，而是一次技术栈与工程规范的全面升级，其核心改进体现在三个方面：

• 更标准化：采用统一的技术栈与目录结构，路由、状态、请求层分工清晰，代码风格可被工具链强制统一；
• 更完善的类型检查机制：基于 TypeScript +vue-tsc，在构建前即可拦截大量类型错误；
• 质的飞跃的运行性能：依托 Vite 的按需编译与原生 ESM 机制，开发与加载速度相较旧版有显著提升。

此外，新版 UI 内置**暗色模式（dark mode）与亮色模式（light mode）**两种主题，满足不同开发者的使用偏好。从 package.json 的依赖清单可以清晰看到其技术构成：Vue 3（Composition API）+ TypeScript 作为框架底座，Naive UI 提供组件库，AntV X6 支撑 DAG 工作流画布编辑，ECharts 承载监控看板图表，Pinia 管理全局状态，Vue Router 组织路由，axios 统一封装 HTTP 请求，vue-i18n 实现中英文国际化。

说明：UI 模块是独立于 Java 后端 reactor 单独构建的，构建产物dist/会被dolphinscheduler-dist模块收编进发布包（见 CLAUDE.md）。因此该模块的构建不依赖 Maven，仅需 Node 工具链即可。

环境准备：Node 与 pnpm 版本要求

为获得最佳开发体验，官方 README 推荐使用node 16.x.x搭配pnpm 7.x.x。这一版本约束并非随意设定，从源码注释与工程实践看（见 CLAUDE.md），Node 版本漂移是该项目最常见的故障源：较新版本 Node（如 18/20）自带的 OpenSSL 行为变化，可能破坏 Vite/Webpack 等构建链路，因此在动手前务必确认当前环境版本：

node -v # 期望输出 v16.x.x pnpm -v # 期望输出 7.x.x

若本机未安装对应版本，请从 node 与 pnpm 官方渠道获取对应版本的安装包（此处不再展开安装细节）。版本确认无误后，进入 UI 模块根目录安装依赖：

# 在仓库根目录下进入 dolphinscheduler-ui pnpm install

pnpm install会依据根目录的 pnpm-lock.yaml 锁定依赖版本，保证团队成员间依赖一致性。安装完成后即可进入下一步的开发或构建流程。

本地开发：配置后端地址并启动 Dev Server

开发模式下，前端需要将 API 请求转发到后端服务。这一步通过项目根目录下的.env.development环境变量文件完成，关键参数为VITE_APP_DEV_WEB_URL。

修改开发环境变量

打开 .env.development，其中默认配置为：

NODE_ENV=development VITE_APP_DEV_WEB_URL='http://127.0.0.1:12345'

按 README 的说明，将VITE_APP_DEV_WEB_URL改为你实际的后端服务地址。这里有一个值得注意的细节：

当你不修改请求路径或路由时，只需填写http、ip和port，结尾不要带/符号，例如http://127.0.0.1:12345。

理解 Dev 代理链路

修改完成后启动开发服务器：

pnpm run dev

该命令实际执行的是 Vite Dev Server（见 package.json 中"dev": "vite"），默认运行于:5173端口。开发模式下的请求链路可以在 vite.config.ts 中看到完整定义：

server: { proxy: { '/dolphinscheduler': { target: loadEnv('development', './').VITE_APP_DEV_WEB_URL, changeOrigin: true } } }

也就是说：Dev Server 将/dolphinscheduler前缀的请求代理到VITE_APP_DEV_WEB_URL指向的后端地址，从而规避开发期的跨域问题。这与 service.ts 中 axios 的baseURL逻辑一一对应——开发模式下请求根路径固定为/dolphinscheduler：

const baseRequestConfig: AxiosRequestConfig = { baseURL: import.meta.env.MODE === 'development' ? '/dolphinscheduler' : import.meta.env.VITE_APP_PROD_WEB_URL + '/dolphinscheduler', ... }

后端dolphinscheduler-api默认监听 12345 端口（与.env.development中的默认值一致），因此「开箱即用」的默认配置即可直接对接本机后端。

开发模式下的请求与鉴权行为

除 baseURL 外，service.ts 还封装了统一的前后端交互约定，开发联调时值得了解：

• 请求拦截器：自动为每个请求注入sessionId请求头（取自用户状态），并读取languageCookie 注入language请求头，用于会话保持与国际化；
• 响应拦截器：统一解包后端返回的{ code, msg, data }结构——code === 0时直接返回data；code缺失时透传原始响应；否则弹出错误消息并抛出异常；
• 会话失效处理：当响应状态码为401或504时，自动清空用户会话并跳转/login登录页（见 service.ts）。

若你在联调中发现接口报 4xx/5xx，可优先核对后端 Controller 与前端 TypeScript 包装方法的参数签名是否对齐（该模块并未生成 OpenAPI SDK，方法签名由人工维护）。

生产构建：配置线上后端地址并打包

开发调试完成后，需要打包部署时，构建流程通过.env.production文件控制。在打包之前，请修改其中的VITE_APP_PROD_WEB_URL参数，确保打包产物能正确请求到线上后端服务地址。

查看 .env.production，其默认内容为：

NODE_ENV=production VITE_APP_PROD_WEB_URL=''

按实际部署场景将其填充为后端网关地址（同样遵循「不含结尾/」的填写规范）。随后执行生产构建：

pnpm run build:prod

该命令的执行链条（见 package.json）为：

"build:prod": "vue-tsc --noEmit && vite build --mode production"

即先执行vue-tsc --noEmit做全量类型检查，再执行 Vite 生产构建——任何类型错误都会中断打包，从工程上保证了产物的类型安全。构建完成后产物输出到dist/目录。

生产构建的几项关键行为

• 资源基础路径：生产模式下的资源基础路径为/dolphinscheduler/ui/（见 vite.config.ts），部署时需将构建产物放置于该路径下，或由反向代理将/dolphinscheduler/ui/映射到dist/；
• Gzip 预压缩：Vite 配置了vite-plugin-compression，对大于 10KB 的文件生成.gz变体（源文件保留），提升静态资源传输效率（见 vite.config.ts）。若排查线上资源加载异常，需确认 Web 服务器是否正确服务.gz变体；
• 产物归属：构建出的dist/由dolphinscheduler-dist模块收集并打入发布包（位于ui/目录下），因此在从仓库打包发布前，务必先执行pnpm run build:prod（见 CLAUDE.md）。

参与前端开发：格式化与类型检查

若你想为dolphinscheduler-ui贡献代码，README 明确了提交前的两道必备工序。

代码格式化

修改代码后，首先执行统一格式化，保证项目代码风格一致：

pnpm run prettier

该脚本对应prettier --write "src/**/*.{vue,ts,tsx}"（见 package.json），会按项目约定的 Prettier 规则重排src下所有 Vue/TypeScript/TSX 源文件。项目同时配置了 ESLint（pnpm run lint，对应eslint src --fix --ext .ts,.tsx,.vue），可在格式化基础上进一步做静态检查。

类型检查

涉及 UI 开发时，请务必在提交代码前执行类型检查，确保无误后再提交：

vue-tsc --noEmit

vue-tsc会对整个项目的 TypeScript 与 Vue 单文件组件做严格类型推导。由于生产构建本身也会先跑这一检查，提前本地执行可避免构建阶段才暴露类型问题。

源码结构速览：理解这套 UI 的组织方式

为了在开发中快速定位代码，了解src目录的分层设计很有帮助（可对照 CLAUDE.md 与 src 目录）：

应用入口 main.ts 展示了各模块的装配关系：创建 Vue 应用实例后依次挂载@vitejs/plugin-vue编译出的根组件、Vue Router、Pinia（含持久化插件pinia-plugin-persistedstate）与 vue-i18n，同时将 ECharts 挂载为全局属性供图表页面直接使用。

其中值得特别留意的两点：

• DAG 工作流编辑器（views/projects/workflow/components/dag/，基于 AntV X6）是全项目最复杂的视图模块，改动时需格外谨慎（见 CLAUDE.md）；
• 国际化：当前支持en_US与zh_CN两种语言，语言切换通过languageCookie（js-cookie）持久化，UI 渲染与请求头均读取该值。

常见问题与排查建议

• pnpm run dev后接口 404/无法连接后端：检查.env.development中VITE_APP_DEV_WEB_URL是否指向可达的后端地址，且未带结尾/；
• 打包产物访问后资源 404：确认dist/是否部署在/dolphinscheduler/ui/路径下，或反向代理是否正确转发该前缀；
• 构建报类型错误：vue-tsc --noEmit报错会直接中断build:prod，按报错修正类型后再重新构建；
• Node 版本不兼容：优先切换到推荐版本（node 16.x + pnpm 7.x），再重新执行pnpm install与pnpm run dev；
• 线上资源加载异常：检查 Web 服务器是否正确处理 Vite 预压缩生成的.gz文件（Content-Encoding: gzip）。

以上排查路径均可在 README、vite.config.ts、service.ts 与 CLAUDE.md 中找到对应的配置依据。

【免费下载链接】dolphinschedulerApache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code项目地址: https://gitcode.com/GitHub_Trending/dol/dolphinscheduler