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

从源码构建 WeKanbuild.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-itWeKan v4.29 将 markdown 渲染从 marked 切换到 markdown-it。切换带来的直接收益是插件生态引入了 markdown-it-emoji 插件支持完整的 GitHub emoji 列表例如在卡片标题、卡片描述中写:rainbow: :thumbsup: :100:即可显示对应 emojimarkdown-it 的语法扩展机制允许挂载更多插件如 mermaid 图表语法这正是本文后半部分“如何添加新插件”要解决的问题。仓库中的实际实现证据当前仓库中 markdown 渲染位于本地 Meteor 包 packages/markdown/package.js其摘要已写明“GitHub flavored markdown parser for Meteor based on markdown-it”并且同时声明了两个大版本的 Meteorapi.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. 安装并配置 gitsudo apt -y install git git config --global user.name Yourfirstname Yourlastname git config --global user.email email-address-you-use-at-githubexample.com git config --global push.default simple nano .ssh/config在.ssh/config中添加 GitHub 用户名与身份文件IdentityFile是你的 SSH 私钥不是.pub公钥缩进用一个 Tab例如Host * IdentitiesOnlyyes 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编辑~/.bashrcnano .bashrc在文件底部添加export PATH~/.meteor:$PATH保存退出。2. 克隆你的 Fork在 GitHub 网页上 Fork 官方 wekan 仓库后mkdir repos cd repos git clone gitgithub.com:YourGithubUsername/wekan.git cd wekan3. 用 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 # 构建 WeKanSetup - Build WeKan ./build.sh 1 # Setup 2 # Build WeKan # 以开发模式运行Dev server - localhost:3000 ./build.sh 2 # Dev server 1 # localhost:3000Setup - 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_SNAPSHOT1生成堆快照定位内存占用者。Dev server - localhost:3000用meteor命令以开发模式启动检测文件变化并自动重建、刷新浏览器。脚本实际执行的命令带有若干环境变量DEFAULT_METEOR_REACTIVITY_ORDERchangeStreams,oplog,polling DDP_TRANSPORTsockjs \ DEBUGtrue WRITABLE_PATH.. WITH_APItrue RICHER_CARD_COMMENT_EDITORfalse \ ROOT_URLhttp://localhost:3000 meteor run --port 3000 21 | tee .tools/log/wekan-log.log其中WITH_APItrue开启 REST APIROOT_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 端口与devServerPort8080匹配进程再对应用端口、rspack 端口和捆绑 Mongo 端口应用端口1逐一探测释放15 秒后仍未释放则升级为 SIGKILL。其余Dev server选项以不同地址/端口运行 WeKan与 build.sh 中的菜单一一对应localhost:3000 trace warnings附加WARN_WHEN_USING_OLD_APItrue 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连接外部 MongoDBMONGO_URLmongodb://127.0.0.1:27019/wekanCUSTOM-IP:PORT交互式询问 IP 与端口Kill all dev servers一次性释放脚本使用的所有开发/测试端口。脚本中该列表定义为DEV_SERVER_PORTS3000 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 并删除旧 Meteorsudo n 20.15.0 sudo npm -g install npm cd rm -rf .meteor然后参考 Meteor 官方仓库中 Meteor 3 相关 PR 的说明安装新版 Meteor例如npx meteorrc查看并切换到 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输出的提示移除已弃用的依赖、换用仍在维护的替代品。更新 Meteormeteor update # 更新到下一个 Meteor 发布版 meteor update --release METEOR3.0-rc.4 # 更新到指定发布版 meteor update --release METEOR3.0-rc.4 --all-packages # 尝试更新所有 Meteor 包 meteor update --release METEOR3.0-rc.4 --all-packages --allow-incompatible-update # 允许不兼容更新有时可行如果同时更换了 Meteor 与 Node.js 版本可能需要重置 Meteormeteor reset或者在你确认自己做的改动可以丢弃时直接删除 WeKan 仓库重新克隆再按前文流程构建。五、构建机制的源码级补充堆内存与工具链为了让构建过程“可复现、可排障”build.sh 在启动时做了两件值得了解的事动态计算 Node 堆上限不再硬编码 8192 MB而是取“可用内存的一半、上限 16384 MB”同时写入TOOL_NODE_FLAGSMeteor 命令行进程与NODE_OPTIONS子 Node/rspack 进程并支持预先导出这两个变量来覆盖默认值。脚本注释中记录了硬编码 8192 导致“8146 MB/8192 MB 处 OOM”的失败案例这也是改为按机器动态计算的原因。仓库本地工具链脚本会把 Meteor 与 Node 安装到仓库内的.tools/目录并优先加入 PATH该目录同时被.gitignore与.meteorignore排除保证无人值守的构建/测试入口不会因为新 shell 找不到meteor而失败测试数据库、测试文件等运行期目录也统一放在.tools/下的忽略路径中。此外脚本每次运行都会先检查并在权限允许时自动提高fs.inotify.max_user_watchesMeteor 文件监视器每个目录占用一个 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 --npmmeteor npm installmeteor 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 能力贡献新的插件扩展。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考