企业官网建设流程全解析

• 音视频
• 即时通讯
• 教育
• 前端
• 桌面应用

Agora Flat 是 Agora（声网）开源的在线教室客户端项目，本仓库提供其 Web 端、Windows 与 macOS 桌面端的完整实现。本文以仓库中文 README（docs/readme/README-zh.md）为主线，系统讲解 Flat 的核心功能特性、无服务端本地构建流程、Electron 与 Web 双端启动/打包命令，并结合仓库源码与配置文件说明每条命令背后的执行链路，帮助你快速跑通整个客户端工程并理解其工程组织方式。

图片说明：Flat 客户端主界面展示，涵盖互动白板、音视频课堂等核心场景（来源：docs/readme/README-zh.md 顶部展示图）。

一、项目概览：一个 Monorepo 中的两类客户端

Flat 项目采用 pnpm workspace 组织为单仓库（Monorepo），根目录的 pnpm-workspace.yaml 声明了desktop/**、web/**、packages/**、service-providers/**四类工作区，将桌面端、Web 端、共享业务包与服务提供商（service provider）集中在同一仓库中维护。仓库内主要包含两个可独立构建的客户端工程：

• Flat Electron 客户端（desktop）：基于 Electron 的桌面实现，主进程位于desktop/main-app，渲染层位于desktop/renderer-app，通过 esbuild / webpack 分别构建主进程与渲染进程；
• Flat Web 客户端（web）：基于 Vite 的 Web 实现，具体工程位于 web/flat-web。

共享业务逻辑集中在 packages 下的flat-components（UI 组件库）、flat-pages（页面）、flat-stores（状态管理）、flat-server-api（服务端 API 封装）、flat-i18n（国际化文案）、flat-types（类型定义）等包中；底层音视频、白板等能力则通过 service-providers 下的各服务提供商（如agora-rtc、agora-rtm、fastboard、file-convert-netless、file-preview-netless）以插件化方式接入。

根目录 package.json 还通过preinstall钩子执行npx only-allow pnpm，强制使用 pnpm 作为包管理器；prepare钩子执行husky install以启用 Git 提交钩子。

二、核心特性全景：实时课堂的六类能力

README 将 Flat 的能力归纳为六大类，下面逐项结合仓库代码给出对应的实现落点，便于你在阅读源码时按图索骥。

1. 实时交互

• 多功能互动白板：白板能力由service-providers/fastboard（基于 Netless Whiteboard 的 fastboard 封装）与service-providers/file-convert-netless（课件转换）、file-preview-netless/file-preview-netless-slide（文档预览）协同提供，白板状态管理见 packages/flat-stores/src/whiteboard-store/index.ts；
• 实时音视频（RTC）：桌面端通过 service-providers/agora-rtc/agora-rtc-electron 接入 Agora 音视频 SDK，Web 端通过 service-providers/agora-rtc/agora-rtc-web 接入；
• 即时消息（RTM）聊天：由 service-providers/agora-rtm 与agora-rtm2提供信令与群聊能力，课堂内的聊天状态管理见 packages/flat-stores/src/classroom-store/chat-store.ts。

2. 登录方式

支持微信与 GitHub 两种第三方登录，桌面端与 Web 端的登录逻辑见 packages/flat-pages/src/LoginPage（内含githubLogin.ts、googleLogin.ts、agoraLogin.ts、WeChatLogin.tsx等），服务端登录协议封装见 packages/flat-server-api/src/login.ts。

3. 房间管理

支持加入、创建、预定房间，并支持周期性房间（周期课）。房间相关 API 封装见 packages/flat-server-api/src/room.ts，周期性房间页面见 packages/flat-pages/src/PeriodicRoomDetailPage 与ModifyPeriodicRoomPage。

4. 课堂录制回放

• 白板信令回放：见 packages/flat-pages/src/ReplayPage/ReplayWhiteboard.tsx；
• 音视频云录制回放：云录制服务由 service-providers/agora-cloud-recording 封装，回放页面见 packages/flat-pages/src/ReplayPage/ReplayVideo.tsx；
• 群聊信令回放：见 packages/flat-pages/src/ReplayPage/ReplayList.tsx 与回放状态管理 packages/flat-stores/src/classroom-replay-store。

5. 多媒体课件云盘

课件云盘支持上传、转换与预览，UI 与容器见 packages/flat-components/src/components/CloudStorage 与 packages/flat-components/src/containers/CloudStorageContainer，服务端 API 见 packages/flat-server-api/src/storage.ts。

6. 屏幕共享

屏幕共享能力由 RTC 服务提供商实现：桌面端见 service-providers/agora-rtc/agora-rtc-electron/src/rtc-share-screen.ts，Web 端见 service-providers/agora-rtc/agora-rtc-web/src/rtc-share-screen.ts。

三、环境准备：pnpm 安装与依赖拉取

Flat 使用 pnpm 作为包管理器，且根目录 package.json 的preinstall钩子会强制校验。若本机尚未安装 pnpm，先全局安装：

npm i -g pnpm

克隆（或 fork）仓库后，在项目根目录执行依赖安装：

pnpm i

pnpm i会按照 pnpm-workspace.yaml 解析工作区，为desktop、web、packages、service-providers下的所有子包统一安装依赖并建立软链接。

桌面端依赖的坑：Electron 镜像与 agora 原生插件

构建 Electron 客户端涉及两个常见网络问题，README 与仓库配置均有对应处理：

1. Electron 二进制下载失败：若因网络问题无法下载 Electron，可在项目目录新建.npmrc文件并写入如下内容后重新执行pnpm i：

   ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"

2. Agora 原生插件（agora-electron-sdk）：该插件体积较大且通过 postinstall 脚本下载，因此根目录 package.json 的pnpm.neverBuiltDependencies中声明了agora-electron-sdk，注释明确说明"我们会在@netless/flat-service-provider-agora-rtc-electron的 postinstall 脚本中下载它"。相关下载逻辑见 service-providers/agora-rtc/agora-rtc-electron/scripts/download-agora-addon。

四、构建并运行 Flat Electron 客户端

在仓库根目录执行：

pnpm start

该命令在根目录 package.json 中定义为node scripts/launch/index.js。启动脚本 scripts/launch/index.js 会根据操作系统分发启动方式：

• Windows：调用scripts\launch\start.cmd（见 scripts/launch/start.cmd）；
• macOS：先用 AppleScript 探测是否安装了 iTerm2（scripts/launch/mac/exists_iTerm.scpt），若存在则通过launch_iTerm.scpt打开 iTerm2 启动，否则回退到系统终端launch_terminal.scpt（相关脚本见 scripts/launch/mac）。

启动脚本还会读取环境变量FLAT_REGION，并据此拼接启动后缀：FLAT_REGION缺省时不追加后缀，取值为CN或SG时分别追加:cn/:sg。这也解释了根目录为何同时存在start:cn与start:sg（cross-env FLAT_REGION=CN node scripts/launch/index.js）——用于指定接入不同区域的服务配置。

真正驱动桌面端开发构建的是 desktop/main-app/package.json 中的脚本：

• start：cross-env NODE_ENV=development esbuild-dev --cjs scripts/esbuild/esbuild.dev.ts，通过 esbuild 增量编译主进程（配置见 desktop/main-app/scripts/esbuild/esbuild.dev.ts）；
• build：cross-env NODE_ENV=production esbuild-dev --cjs scripts/esbuild/esbuild.prod.ts，产出生产构建；
• 渲染进程则走 webpack 构建体系（desktop/main-app/webpack），其产物（desktop/renderer-app/dist）由主进程加载。

打包为可执行文件

README 给出了三种打包方式，均需在仓库根目录执行：

pnpm ship # 根据当前系统打包 pnpm ship:mac # 针对 macOS 打包 pnpm ship:win # 针对 Windows 打包

以根目录脚本定义看，它们的实际执行链路为：

• pnpm ship→pnpm -F renderer-app build && pnpm -F flat ship，即先构建渲染层，再进入desktop/main-app执行ship；
• pnpm ship:mac→pnpm -F renderer-app build && pnpm -F flat ship:mac；
• pnpm ship:win→pnpm -F renderer-app build && pnpm -F flat ship:win。

desktop/main-app侧对应脚本（见 desktop/main-app/package.json）：

• ship：pnpm build && node ./scripts/pack auto（auto表示按当前系统选择平台）；
• ship:win：pnpm build && pnpm pack:win；
• ship:mac：pnpm build && pnpm pack:mac。

打包程序 desktop/main-app/scripts/pack/index.js 内部通过 electron-builder 完成构建，关键流程包括：

1. 读取FLAT_REGION（缺省为CN，见 scripts/utils/auto-choose-config.js 与 scripts/constants.js），并从 desktop/main-app/electron-builder 下加载对应的CN.yml/SG.yml配置；
2. 调用 Agora 原生插件下载脚本（download-agora-addon）按目标平台拉取对应的 Agora SDK 原生模块；
3. 将渲染层产物desktop/renderer-app/dist作为extraResources拷入安装包，macOS 额外打入resources/macOS/locals本地化资源；
4. 若为 macOS 且SKIP_MAC_NOTARIZE不为no，则挂接 desktop/main-app/scripts/pack/notarize.js 进行公证；Windows 打包若设置了WINDOWS_CODE_SIGNING_SERVER或证书环境变量，则启用 desktop/main-app/scripts/pack/sign.js 完成签名；
5. 打包完成后若当前系统与目标平台不一致，会恢复 Agora 原生插件到开发环境对应版本，避免影响后续开发。

以CN.yml（desktop/main-app/electron-builder/CN.yml）为例，可看到桌面安装包的关键产物配置：

• 通用：appId: io.agora.flat，productName: Flat，产物命名Flat-${arch}-${version}.${ext}，启用asar；
• macOS：同时产出zip与dmg，arch 覆盖x64与arm64，启用hardenedRuntime与公证所需的 entitlements（entitlements.mac.plist），并注册x-agora-flat-clientURL Scheme；
• Windows：产出zip与nsis（x64），NSIS 安装器允许选择安装目录、创建桌面与开始菜单快捷方式；
• 协议：注册x-agora-flat-client自定义协议，用于唤起客户端。

区域配置说明：仓库 config 目录下按CN/SG划分部署环境，打包与启动脚本通过FLAT_REGION环境变量选择对应配置，因此同一份代码可以构建出接入不同区域服务的客户端（根目录还提供了start:cn/start:sg/ship:cn:all/ship:sg:all等便捷命令）。

五、构建并运行 Flat Web 客户端

README 提供了两条等价命令，任选其一在仓库根目录执行：

pnpm start:web

或：

cd ./web/flat-web/ && pnpm start

两条命令最终都进入 web/flat-web 工程：pnpm start:web等价于pnpm -F flat-web start（-F表示在指定 workspace 包内执行），后者在 web/flat-web/package.json 中定义为vite --open，即以 Vite 启动开发服务器并自动打开浏览器。

Web 工程同样支持区域切换与生产构建：

• start:cn/start:sg：cross-env FLAT_REGION=CN pnpm start/FLAT_REGION=SG；
• build：cross-env NODE_OPTIONS="--max-old-space-size=8192" vite build（扩容 Node 内存上限以支撑大型构建）；
• build:cn/build:sg：分别以对应区域配置执行构建；
• serve：vite preview预览生产构建产物。

从依赖看，Web 端通过 workspace 依赖引用了@netless/flat-pages、@netless/flat-stores、@netless/flat-services及各flat-service-provider-*包（RTC Web、RTM、云录制、课件转换与预览等），其页面与业务逻辑集中在 packages/flat-pages/src，入口初始化流程见 web/flat-web/src/tasks。

六、UI 与业务逻辑分离：用 Storybook 预览组件

Flat 的 UI 与业务逻辑分离开发。README 建议通过 Storybook 快速查看与开发部分 UI，本地启动方式为在仓库根目录执行：

pnpm storybook

该命令在根目录 package.json 中定义为pnpm -F flat-components start，进入 packages/flat-components 组件库包执行 Storybook 启动脚本。该包的 package.json 中：

• start：start-storybook -p 6006 -s public --no-version-updates，即在6006端口启动 Storybook 开发服务器；
• build：build-storybook -s public，可产出静态 Storybook 站点。

组件库源码位于 packages/flat-components/src/components，覆盖课堂（ClassroomPage）、登录（LoginPage）、主页（HomePage）、云盘（CloudStorage）、设置（SettingPage）等完整业务组件，并配有 packages/flat-components/src/theme 下的主题与样式体系（antd 定制、颜色变量等），是快速理解 Flat UI 结构的最佳入口。

七、继续深入：参考文档与周边项目

仓库内参考文档

中文 README 指向的三份仓库内文档同样值得一读：

• 发布版本说明：按版本号组织的发布记录（v1.0.0至v2.3.6，均提供中英文说明，如 docs/releases/v2.3.6/zh.md）；
• 调试 Flat：其中 Electron 主进程调试指南见 docs/debugging/electron/README-zh.md；
• 贡献指南：涵盖改进文档、改善问题、反馈问题等协作方式。

周边项目

README 列出的相关项目包括 Flat 安卓客户端、Flat 服务端与 Flat 主页，其中服务端负责登录鉴权、房间与云盘等业务 API，客户端仓库内的对应协议封装可参考 packages/flat-server-api/src 下的login.ts、room.ts、storage.ts、recording.ts等模块。

开源许可与使用注意

• 仓库采用 MIT 许可证（见 LICENSE），可自由用于学习与商业场景；
• 官方声明：可以商用，但官方不提供商业化需求定制、部署支持与客户服务；
• 项目仅用于学习与交流，请遵守所在国法律法规，勿用于政治、宗教、色情、犯罪等领域。

八、常见问题速查

通过本文的命令与源码对照，你已掌握 Flat 双端客户端的完整构建链路：pnpm i安装依赖 →pnpm start/pnpm start:web本地开发 →pnpm ship/pnpm ship:mac/pnpm ship:win产物打包，并理解了FLAT_REGION区域配置、Electron 镜像与 Agora 原生插件等关键工程细节。接下来即可基于 desktop 与 web 两个工程目录展开二次开发。

• 音视频
• 即时通讯
• 教育
• 前端
• 桌面应用