Focalboard 插件版开发指南：从源码构建 Mattermost Boards 插件到上传部署

Focalboard 插件版开发指南：从源码构建 Mattermost Boards 插件到上传部署

【免费下载链接】focalboardFocalboard is an open source, self-hosted alternative to Trello, Notion, and Asana.项目地址: https://gitcode.com/GitHub_Trending/fo/focalboard

Focalboard 插件版（前身为 Mattermost Boards 插件）自 2023 年 9 月 15 日起已全面移交社区维护，其源码持续开源可用。本文以 docs/focalboard-dev-guide.md 为主线，完整梳理从源码构建插件包（.tar.gz）、手动上传到 Mattermost 服务器，以及借助make deploy在本地 Mattermost 环境自动部署的全流程，并结合当前仓库的 Makefile、webapp/package.json 与 CI 工作流 .github/workflows/dev-release.yml 做源码级印证。读完本文，你将掌握插件版 Focalboard 的完整构建链路、Mattermost 侧三个关键配置项（SiteURL、EnableLocalMode、EnableUploads）的含义与设置方法，以及本地联调部署的标准姿势。

背景：Focalboard 插件版与社区化交接

Focalboard 是开源的、可自托管的项目管理工具（README.md 将其定位为 Trello、Notion、Asana 的开源替代品）。在其生态中，除独立版（standalone）之外，还存在一个以 Mattermost 插件形态分发的版本——即 Mattermost Boards 插件，也就是本文所说的Focalboard 插件版。

官方开发指南在开篇明确了一则重要交接信息：

自2023 年 9 月 15 日起，Mattermost Boards 全面转变为社区支持的 Focalboard 插件。Mattermost 将不再维护该插件（包括 bug 修复与功能新增），而是将其开源并无限期保留在 GitHub 上供社区贡献。

这一背景决定了本指南的两个核心动作：

1. 自行构建：从源码构建你自己的插件版本；
2. 自行部署：把构建产物上传到你的 Mattermost 服务器。

需要特别说明的是，当前仓库（fo/focalboard）只包含独立版（standalone）Focalboard。README.md 顶部的警告明确指出："This repository only contains standalone Focalboard. If you're looking for the Mattermost plugin please see mattermost/mattermost-plugin-boards."（本仓库仅含独立版 Focalboard；如需 Mattermost 插件版请见 mattermost-plugin-boards 仓库。）因此，本文涉及的mattermost-plugin目录与其中的make dist/make deploy目标属于插件版仓库，而make prebuild、make webapp等通用构建目标在当前仓库的 Makefile 中均有对应实现——阅读下文时请注意这一适用范围。

构建流程总览

插件版的构建与部署可以归纳为三步，后续章节逐一展开：

第一步：搭建开发环境并安装依赖

官方指南要求先 Fork Focalboard 仓库、克隆到本地，然后按照 README 完成开发环境初始化。依赖安装的命令如下：

# First-time setup dependencies cd mattermost-plugin/webapp npm install --no-optional cd ../.. make prebuild

对这三条命令逐一说明：

• cd mattermost-plugin/webapp && npm install --no-optional：进入插件版前端目录安装 npm 依赖。--no-optional用于跳过optionalDependencies，避免安装 Cypress 等非必需的可选依赖。这一习惯与当前仓库的 CI 一致——.github/workflows/dev-release.yml 中同样使用cd focalboard/webapp; npm ci --no-optional（npm ci是 CI 环境下更严格的锁文件安装方式）。当前仓库的 webapp/package.json 也将cypress声明在optionalDependencies中，印证了--no-optional的用意。
• make prebuild：执行仓库预构建动作。当前仓库根 Makefile 中该目标定义为cd webapp; npm install（另有cleanall目标用于清理webapp/node_modules）。在插件版同库时代，make prebuild负责安装其余子模块依赖。

提示：官方指南强调，具体以 CI 工作流 dev-release.yml 中实际执行的命令为准。该工作流在当前仓库中负责各平台产物的发布构建（例如 Windows WPF 应用、macOS 应用等），其npm ci --no-optional、make win-wpf-app等步骤可作为"CI 与本地命令保持一致"的参考范式。

第二步：构建 webapp 与插件包

依赖就绪后，依次执行两条构建命令：

# Build webapp make webapp # Build plugin cd mattermost-plugin make dist

make webapp负责构建前端资源。在当前仓库 Makefile 中，该目标实现为cd webapp; npm run pack，而 webapp/package.json 中pack脚本为：

"pack": "cross-env NODE_ENV=production webpack --config webpack.prod.js"

即使用生产环境变量并调用 webapp/webpack.prod.js 进行 webpack 打包。在插件版中，构建出的前端资源会被内嵌进插件包。

cd mattermost-plugin && make dist负责把插件前端与 Go 后端组装成 Mattermost 插件规范要求的plugin.tar.gz格式包（mattermost-plugin/dist/目录）。该目标是插件版仓库（迁移后的 mattermost-plugin-boards）内定义的构建目标，产物即可直接用于上传。

第三步：上传插件到 Mattermost 服务器（手动方式）

构建得到.tar.gz插件包后，官方指南给出两种上传途径，第一种是手动上传：

1. 开启自定义插件上传：在 Mattermost 服务器的config.json文件中，将PluginSettings > EnableUploads设置为true。该开关控制 System Console 是否允许管理员上传自定义插件，属于插件安装的前置条件。
2. 进入控制台上传：导航到System Console > Plugins > Management，选择并上传mattermost-plugin/dist目录下生成的.tar.gz包。
3. 启用插件：上传后按需在插件管理页面启用它。

需要区分两个容易混淆的config.json：

• 上文修改的是Mattermost 服务器的config.json（位于 mattermost-server 仓库中，由make config-reset生成）；
• 而当前仓库根目录的 config.json 是Focalboard 独立版服务器的配置（包含serverRoot、port、dbtype、webpath等项），与插件上传无关，二者不要混为一谈。

本地 Mattermost 环境搭建（供 make deploy 自动部署使用）

第二种途径是本地安装 Mattermost 后使用make deploy自动部署，适合插件开发期的快速迭代。官方指南将其拆分为"搭建 Mattermost"与"构建部署插件"两个阶段。

阶段一：本地构建并运行 Mattermost

1. 准备 Docker：按照 Mattermost 开发者指南搭建环境，尤其要确保 Docker 已安装并运行（Mattermost 的依赖服务常以容器方式提供）。
2. 构建 Web 端：Fork 并克隆mattermost-webapp，执行make build。
3. 克隆服务端：Fork 并克隆mattermost-server。
4. 生成配置：在 mattermost-server 中执行make config-reset，生成config/config.json。
5. 编辑config/config.json，需要修改三个关键配置项：

6. 设置环境变量：添加环境变量MM_SERVICESETTINGS_SITEURL，其值必须与config.json中的SiteURL保持一致（即http://localhost:8065）。Mattermost 支持通过环境变量覆盖对应配置项，二者不一致会导致连接与上传失败。
7. 启动服务器：在 mattermost-server 中运行make run-server。

阶段二：构建并部署插件

Mattermost 跑起来之后，回到 Focalboard（插件版）仓库：

make webapp cd mattermost-plugin make deploy

make webapp先构建前端，make deploy则利用前面配置好的SiteURL、EnableLocalMode、EnableUploads与MM_SERVICESETTINGS_SITEURL，把新构建的插件包自动部署到本地 Mattermost 实例并（视目标实现）触发重载，省去每次手动上传的步骤。

关键配置项速查表

将两条路径涉及的配置汇总如下，便于开发与排障时对照：

与当前仓库的关系与适用前提

最后明确几点边界，避免读者在独立版仓库中找不到对应目录而困惑：

1. 当前仓库不含mattermost-plugin目录。独立版与插件版已拆分，插件版代码迁移至mattermost/mattermost-plugin-boards仓库；本文中cd mattermost-plugin之后的命令需在插件版代码库中执行。
2. 通用构建命令依然有效。make prebuild、make webapp在独立版 Makefile 中存在对应实现，独立版还提供server、mac-app、win-wpf-app、linux-app、server-test-*等目标，用于构建独立服务器与各平台桌面应用。
3. 插件版长期开源可自建。由于插件已交由社区维护且无限期开源，任何团队都可以按本指南自建并自托管 Boards 插件，不依赖 Mattermost 官方发布周期——这正是本指南的核心价值所在。

小结

构建并部署 Focalboard 插件版是一条清晰的流水线：先用npm install --no-optional+make prebuild装好依赖，再用make webapp+make dist产出插件包，最后通过 System Console 手动上传，或搭建本地 Mattermost 后用make deploy自动部署。其中 Mattermost 侧的SiteURL、EnableLocalMode、EnableUploads三个配置与MM_SERVICESETTINGS_SITEURL环境变量是打通"构建 → 部署"闭环的关键，务必保持一致。对于希望长期自托管 Boards 能力的团队而言，这套流程在插件社区化的背景下依然完全可用。

【免费下载链接】focalboardFocalboard is an open source, self-hosted alternative to Trello, Notion, and Asana.项目地址: https://gitcode.com/GitHub_Trending/fo/focalboard