从源码构建 WeKan：build.sh 两级菜单、Meteor 2/3 开发服务器与 Markdown-it 插件扩展实战指南-港品优选

从源码构建 WeKan：build.sh 两级菜单、Meteor 2/3 开发服务器与 Markdown-it 插件扩展实战指南

【免费下载链接】wekanThe Open Source kanban, built with Meteor. GitHub issues/PRs are only for FLOSS Developers, not for support, support is at https://wekan.fi/commercial-support/ . PR source translation to imports/i18n/data/en.i18n.json, other translations at https://app.transifex.com/wekan/wekan项目地址: https://gitcode.com/GitHub_Trending/we/wekan

本文基于 WeKan 仓库中的 Build-from-source.md 展开，系统讲解如何从源码安装依赖、编译 WeKan、启动 Meteor 开发服务器，以及如何在 markdown-it 基础上扩展新插件（emoji、mermaid 等）并提交 Pull Request。读完后你可以独立完成 WeKan 的源码构建全流程、区分.build/与_build/两个构建产物的差异、处理开发服务器端口冲突，并掌握 npm/Meteor 依赖的升级与排障方法。

一、背景：WeKan v4.29 起 Markdown 渲染器换为 markdown-it

WeKan v4.29 将 markdown 渲染从 marked 切换到 markdown-it。切换带来的直接收益是插件生态：

引入了 markdown-it-emoji 插件，支持完整的 GitHub emoji 列表，例如在卡片标题、卡片描述中写：

:rainbow: :thumbsup: :100:

即可显示对应 emoji；

markdown-it 的语法扩展机制允许挂载更多插件（如 mermaid 图表语法），这正是本文后半部分“如何添加新插件”要解决的问题。

仓库中的实际实现证据

当前仓库中 markdown 渲染位于本地 Meteor 包 packages/markdown/package.js，其摘要已写明“GitHub flavored markdown parser for Meteor based on markdown-it”，并且同时声明了两个大版本的 Meteor：

api.versionsFrom(['2.16', '3.0']);

这解释了为什么本文档的构建指南同时覆盖 Meteor 2 与 Meteor 3 两条路线——markdown 包本身就是按双版本兼容编写的。

渲染引擎的装配在 packages/markdown/src/template-integration.js：文件顶部导入markdown-it、markdown-it-emoji与markdown-it-math/no-default-renderer，并用new MarkdownIt({...})构造实例。值得注意的是，其中已有一处被注释掉的 mermaid 接入痕迹：

//import markdownItMermaid from "@wekanteam/markdown-it-mermaid";

附近注释还给出了@wekanteam/markdown-it-mermaid的 npm 与 GitHub 仓库出处，以及“markdown-it 默认validateLink会拒绝file:等协议”“普通 markdown-it 没有 task-list 扩展”等踩坑记录。可以推断，社区维护的 mermaid 插件（@wekanteam/markdown-it-mermaid）正是按本文档“添加新插件”流程验证过的，可作为接插件的参照实现。

根目录 package.json 中锁定了对应的 npm 依赖：markdown-it ^15.0.0、markdown-it-emoji ^3.0.0、markdown-it-math ^6.0.0。也就是说，扩展 markdown 语法时新增的插件依赖同样会记录在这里，npm audit时会一并参与安全审计。

路径勘误：原文档提到编辑wekan/packages/markdown/src-integration.js，从当前仓库结构看，该文件已演进为 packages/markdown/src/template-integration.js，按当前实际路径操作即可。

二、Meteor 2 路线：从源码构建 WeKan

原文档以“使用最新的 Ubuntu amd64”为推荐环境。仓库的 build.sh 开头也明确提示：推荐最新的 Debian 或 Ubuntu amd64 发行版、直接装 SSD 或双系统而非虚拟机，速度更快；若非en_US.UTF-8语言环境，需先用sudo dpkg-reconfigure locales安装en_US.UTF-8，否则 MongoDB 可能工作异常；控制台输出还会同步记录到log/目录。

1. 安装并配置 git

sudo apt -y install git git config --global user.name "Yourfirstname Yourlastname" git config --global user.email email-address-you-use-at-github@example.com git config --global push.default simple nano .ssh/config

在.ssh/config中添加 GitHub 用户名与身份文件（IdentityFile是你的 SSH 私钥，不是.pub公钥），缩进用一个 Tab，例如：

Host * IdentitiesOnly=yes Host github.com Hostname github.com User xet7 IdentityFile ~/.ssh/id_xet7ed

用 Ctrl-o、Enter、Ctrl-x、Enter 保存退出。若没有 SSH 密钥：

ssh-keygen

连续按约 3 次 Enter，直到生成私钥~/.ssh/id_rsa与公钥~/.ssh/id_rsa.pub，再把公钥.pub添加到 GitHub 账号的 Web 界面中。

再把 Meteor 加入 PATH：编辑~/.bashrc（nano .bashrc），在文件底部添加：

export PATH=~/.meteor:$PATH

保存退出。

2. 克隆你的 Fork

在 GitHub 网页上 Fork 官方 wekan 仓库后：

mkdir repos cd repos git clone git@github.com:YourGithubUsername/wekan.git cd wekan

3. 用 build.sh 两级菜单完成构建与运行

build.sh是一个两级菜单脚本：顶层选择一个类别编号，再在子菜单中选择具体项（每个子菜单都有Back返回）。原文档给出的顶层为：

1) Setup 2) Dev server 3) Tests 4) Docker 5) Tools 6) Quit

从当前 build.sh 的源码结构看，顶层菜单已扩展为 8 项：Setup、Dev server、Tests、Docker、Releases、CLI commands、Tools、Quit，并支持./build.sh --list、./build.sh <name> [args]的命令行方式调用同一套功能。原文档给出的三项核心操作在菜单中的编号依然有效：

# 安装依赖：Setup -> Install dependencies ./build.sh 1 # Setup 1 # Install dependencies # 构建 WeKan：Setup -> Build WeKan ./build.sh 1 # Setup 2 # Build WeKan # 以开发模式运行：Dev server -> localhost:3000 ./build.sh 2 # Dev server 1 # localhost:3000

Setup -> Install dependencies会按发行版（Debian/Ubuntu、Alpine、Arch、Fedora、RHEL 等）安装 C/C++ 工具链、git、curl、wget、7zip、zip、unzip、npm，然后安装 Node.js 与 Meteor 本身。

Setup -> Build WeKan对应脚本内的build_wekan()函数，实际执行的是：

rm -rf node_modules node_modules/.cache .meteor/local .build _build (meteor update --npm || true) && meteor npm install meteor build .build --directory

也就是说：清理旧依赖与旧产物、同步 npm 依赖、meteor build .build --directory产出发布包，且完整构建日志会tee到本次运行的log/目录。构建失败时脚本还会识别“JavaScript heap out of memory”这类错误并给出具体的诊断提示（例如用WEKAN_BUILD_HEAP_SNAPSHOT=1生成堆快照定位内存占用者）。

Dev server -> localhost:3000用meteor命令以开发模式启动，检测文件变化并自动重建、刷新浏览器。脚本实际执行的命令带有若干环境变量：

DEFAULT_METEOR_REACTIVITY_ORDER="changeStreams,oplog,polling" DDP_TRANSPORT=sockjs \ DEBUG=true WRITABLE_PATH=.. WITH_API=true RICHER_CARD_COMMENT_EDITOR=false \ ROOT_URL=http://localhost:3000 meteor run --port 3000 2>&1 | tee .tools/log/wekan-log.log

其中WITH_API=true开启 REST API，ROOT_URL决定生成的绝对链接，输出同时写入.tools/log/wekan-log.log。偶尔热重载不生效，需要用 Ctrl-c 停掉后重新走一次Setup -> Build WeKan。

启动后按注册用户并登录的说明访问 http://localhost:3000 即可。

4. 两个极易混淆的构建目录：.build/ 与 _build/

构建会产生两个名字相近、含义完全不同的目录，原文档特意强调要分清：

目录	它是什么
`.build/`	发布包（RELEASE bundle），由`meteor build .build --directory`产生。`.build/bundle`才是被部署、测试和打包的内容。
`_build/`	rspack 的编译输出，由任何Meteor 编译（开发运行、测试运行、发布构建）写入。Meteor 从`_build/main-prod/`读取应用主模块，因此它是“交接物”而非“垃圾残留”。

两者都是生成物、均被 gitignore，任何时候都不要编辑或提交它们。特别地，_build/绝不能加入.meteorignore——忽略它会直接打断构建，该文件中也有注释说明原因。另外_build/内持有每个源文件的一份捆绑副本，所以任何遍历仓库的脚本都应跳过它。build.sh 开头的启动提示也逐条重申了这些规则。

5. 开发服务器的端口管理与其它 Dev server 选项

若已有开发服务器在运行，Dev server各选项会先自动停掉旧服务器再启动新的——同时释放应用端口和rspack 开发服务器端口8080（残留的 rspack 进程会让新服务器以Error: listen EADDRINUSE ... :8080崩溃），无需手动杀进程。从 build.sh 源码看，这一逻辑由kill_meteor_on_port()实现：先按meteor run --port <端口>与devServerPort=8080匹配进程，再对应用端口、rspack 端口和捆绑 Mongo 端口（应用端口+1）逐一探测释放，15 秒后仍未释放则升级为 SIGKILL。

其余Dev server选项以不同地址/端口运行 WeKan，与 build.sh 中的菜单一一对应：

localhost:3000 + trace warnings：附加WARN_WHEN_USING_OLD_API=true NODE_OPTIONS=--trace-warnings，暴露将被 Meteor 3 移除的旧 API 警告；
localhost:3000 + bundle visualizer：追加--extra-packages bundle-visualizer --production，可视化打包体积；
CURRENT-IP:3000：自动探测本机 IP 并以该地址运行；
CURRENT-IP:3000 + MONGO_URL 27019：连接外部 MongoDB（MONGO_URL=mongodb://127.0.0.1:27019/wekan）；
CUSTOM-IP:PORT：交互式询问 IP 与端口；
Kill all dev servers：一次性释放脚本使用的所有开发/测试端口。脚本中该列表定义为DEV_SERVER_PORTS="3000 3001 3100 3101 4000 4001 8080"（开发应用及其 Mongo、Mocha 测试服务器及其 Mongo、Sandstorm 开发服务器及其 Mongo、rspack 开发服务器），适合上次运行留下残余进程时使用。

6. 可选：添加新的 markdown-it 插件

以下两步原文档标注为 OPTIONAL, NOT NEEDED，仅在你要为 WeKan 增加 markdown 语法扩展时才需要。

安装新插件包：

meteor npm install markdown-it-something --save

编辑 markdown 包源码（当前仓库实际路径为 packages/markdown/src/template-integration.js），仿照其中 emoji 插件（markdown-it-emoji）或数学公式插件（markdown-it-math）的接入方式，用新插件页面上的代码示例完成挂载。

7. 测试新插件语法

在卡片标题、卡片描述等输入字段中测试新插件语法是否生效。

8. 验证通过后创建 Pull Request

普通 markdown、emoji 与新插件语法都正常时，提交你的改动：

git add --all git commit -m "Added plugin markdown-it-something." git push

然后在你的 Fork 仓库页面上点击Create pull request。仓库根目录的 CONTRIBUTING.md 也有关于贡献流程的补充约定，建议一并阅读。

三、Meteor 3 路线

原文档记录了一次 Meteor 3 升级尝试（以 2024-06-26 为参考时点）。核心步骤：确认当时的 Node.js LTS 版本（示例为 20.15.0），切换到最新 LTS 并删除旧 Meteor：

sudo n 20.15.0 sudo npm -g install npm cd rm -rf .meteor

然后参考 Meteor 官方仓库中 Meteor 3 相关 PR 的说明安装新版 Meteor，例如：

npx meteor@rc

查看并切换到 Meteor 3 特性分支：

cd repos/wekan git branch -a git checkout feature-meteor3

构建（Setup -> Build WeKan）：

./build.sh 1 # Setup 2 # Build WeKan

若出现报错，逐个修复；也可以直接尝试运行（Dev server -> localhost:3000）：

./build.sh 2 # Dev server 1 # localhost:3000

从 packages/markdown/package.js 的api.versionsFrom(['2.16', '3.0'])看，本地 markdown 包已按 Meteor 3 做了版本声明，属于这条升级路线中需要同步核对的本地 Meteor 包之一。

四、日常更新：npm 包与 Meteor 版本

依赖更新通常同时涉及 npm 包与 Meteor 两部分。

更新 npm 包

npm update # 更新 npm 包 npm audit # 检查存在漏洞的包 npm audit fix # 通过升级修复漏洞包 npm audit fix --force # 上面无效时强制升级

若npm audit fix --force仍无法解决，按照npm audit输出的提示移除已弃用的依赖、换用仍在维护的替代品。

更新 Meteor

meteor update # 更新到下一个 Meteor 发布版 meteor update --release METEOR@3.0-rc.4 # 更新到指定发布版 meteor update --release METEOR@3.0-rc.4 --all-packages # 尝试更新所有 Meteor 包 meteor update --release METEOR@3.0-rc.4 --all-packages --allow-incompatible-update # 允许不兼容更新（有时可行）

如果同时更换了 Meteor 与 Node.js 版本，可能需要重置 Meteor：

meteor reset

或者（在你确认自己做的改动可以丢弃时）直接删除 WeKan 仓库重新克隆，再按前文流程构建。

五、构建机制的源码级补充：堆内存与工具链

为了让构建过程“可复现、可排障”，build.sh 在启动时做了两件值得了解的事：

动态计算 Node 堆上限：不再硬编码 8192 MB，而是取“可用内存的一半、上限 16384 MB”，同时写入TOOL_NODE_FLAGS（Meteor 命令行进程）与NODE_OPTIONS（子 Node/rspack 进程），并支持预先导出这两个变量来覆盖默认值。脚本注释中记录了硬编码 8192 导致“8146 MB/8192 MB 处 OOM”的失败案例，这也是改为按机器动态计算的原因。
仓库本地工具链：脚本会把 Meteor 与 Node 安装到仓库内的.tools/目录并优先加入 PATH（该目录同时被.gitignore与.meteorignore排除），保证无人值守的构建/测试入口不会因为新 shell 找不到meteor而失败；测试数据库、测试文件等运行期目录也统一放在.tools/下的忽略路径中。

此外，脚本每次运行都会先检查并（在权限允许时）自动提高fs.inotify.max_user_watches（Meteor 文件监视器每个目录占用一个 watch，耗尽时会报出误导性的 “No space left on device”），以及进程打开文件数上限（捆绑 mongod 建议至少 64000，不足会在长时间测试运行中报 “Too many open files” 后以 ECONNREFUSED 形式连锁失败）。这些机制解释了为什么当前build.sh的启动行为比原文档记录的更“开箱即用”：端口冲突、监视器限额、文件句柄限额等常见故障已在脚本层面被预防或给出明确的手动补救命令。

六、小结

从源码构建 WeKan 的关键脉络可以归纳为：

环境：最新 Ubuntu/Debian amd64 + git/SSH 密钥 + Meteor 在 PATH 中；
构建：./build.sh菜单 Setup -> Install dependencies / Build WeKan，底层是清理产物 +meteor update --npm+meteor npm install+meteor build .build --directory；
运行：Dev server -> localhost:3000 以meteor run --port 3000启动开发模式，脚本自动处理 3000/3001/8080 等端口的旧进程清理；
产物：.build/bundle是发布包，_build/是 rspack 与 Meteor 之间的交接目录，二者皆生成、皆不提交；
扩展：markdown 渲染基于 markdown-it（见 packages/markdown），新插件按“npm 安装 + 在 template-integration.js 中挂载 + 卡片字段实测 + PR”的流程加入；
维护：npm update / npm audit / meteor update保持依赖与 Meteor 版本前进，必要时meteor reset或重新克隆。

按此流程操作，你既能在本地得到与发布物一致的构建产物，也能在 Meteor 2 与 Meteor 3 两条路线之间按需切换，并为 WeKan 的 markdown 能力贡献新的插件扩展。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析