LowCodeEngine 参与贡献指南环境搭建、本地调试与文档、生态、发布全流程【免费下载链接】lowcode-engineAn enterprise-class low-code technology stack with scale-out design / 一套面向扩展设计的企业级低代码技术体系项目地址: https://gitcode.com/GitHub_Trending/lo/lowcode-engine本文基于 lowcode-engine 仓库的官方参与贡献文档docs/docs/participate/index.md撰写完整覆盖从 Node.js 环境准备、monorepo 依赖安装与构建到通过资源代理调试引擎源码、本地维护 Docusaurus 文档站、贡献生态包直至版本发布的全套流程并结合仓库中的 scripts/setup.js、scripts/start.js、packages/ignitor/package.json 等实现细节解释每条命令底层实际执行了什么。读完后你可以独立完成 LowCodeEngine 的本地开发闭环并按仓库规范提交 PR。一、环境准备官方文档明确要求开发 LowCodeEngine 需要Node.js 16推荐使用nvm管理 Node.js 版本一方面避免全局安装带来的权限问题另一方面可以随时切换当前使用的 Node.js 版本。从仓库根目录 package.json 的engines字段可以看到引擎主仓库对 Node 版本的实际约束是14.17.0 18这与Node 16的要求是吻合的16.x 同时满足两者。而文档站 docs/package.json 单独声明了node: 16.14因此若你还要维护文档建议统一使用16.14 及以上、18 以下的 Node 版本。另外从 package.json 的tnpm字段mode: yarn、lockfile: enable与 lerna.json 的npmClient配置可以看到该 monorepo 以yarn workspaces lerna组织依赖这也是后续setup流程中反复清理 lockfile 的原因见下文。二、克隆仓库并安装构建官方给出的起步命令git clone gitgithub.com:alibaba/lowcode-engine.git cd lowcode-engine随后执行依赖安装与构建npm install npm run setup2.1npm run setup到底做了什么setup脚本在根 package.json 中定义为node ./scripts/setup.js。阅读 scripts/setup.js 可以看到它按平台做了分支非 Windows直接执行 scripts/setup.shWindows在 Node 进程内用 gulp 串行执行等价步骤。以 scripts/setup.sh 为准整个流程是四步rm -rf package-lock.json yarn.lock # 1. 删除根目录 lock 文件 lerna clean -y # 2. 清理各子包 node_modules find ./packages -type f -name package-lock.json -exec rm -f {} \; # 3. 删除各子包 lock 文件 lerna bootstrap --force-local # 4. 以 yarn 客户端做本地优先的依赖安装对应地Windows 分支在 scripts/setup.js 中实现了同样四步deleteRootDirLockFile→cleanlerna clean -y→deletePackagesDirLockFile→bootstraplerna bootstrap --force-local。从源码结构看之所以要彻底清理 lock 文件是因为仓库用 yarn workspaces 管理--force-local会优先把packages/*下本地子包互相链接起来避免 npm 客户端生成的 lock 文件干扰 yarn 的 hoist 策略。lerna.json 中的bootstrap.npmClientArgs: [--no-package-lock]也印证了不生成 package-lock的约定。三、启动本地调试服务完成 setup 后进入开发阶段只需一条命令npm startstart脚本同样按平台分发scripts/start.js / scripts/start.sh其本质是lerna exec --scope alilc/lowcode-ignitor -- npm start即定位到 monorepo 中的点火器包 packages/ignitor执行它的start脚本。从 packages/ignitor/package.json 可以看到实际命令{ name: alilc/lowcode-ignitor, description: 点火器bootstrap lce project, scripts: { start: build-scripts start --disable-open --port 5555 } }也就是说npm start会用alib/build-scripts在5555 端口起一个本地开发服务--disable-open表示不自动打开浏览器。这也解释了后文代理规则中所有本地地址为什么都是http://localhost:5555。scripts/start.sh 还支持传入第一个参数来切换调试目标包如npm start pkgName默认值为alilc/lowcode-ignitor从源码结构看这为调试其他子包留了口子。四、调试环境配置把线上产物代理到本地4.1 原理官方文档对调试机制的表述是本质上是将 demo 页面引入的几个 js/css 代理到 engine 项目可以配合趁手的代理工具完成文档推荐 XSwitch浏览器扩展。工作方式是打开一个在线 DEMO 页面例如低代码引擎在线 DEMO该页面正常情况下从uipaas-assets.com的 CDN 加载alilc/lowcode-engine系列产物开启代理后这些 CDN 地址被重写到本地 5555 端口的开发服务输出于是你在 packages/engine 等目录下改动的源码就会实时反映到 DEMO 页面上。4.2 本地开发代理规则官方文档给出的完整代理规则XSwitch JSON 格式{ proxy: [ [ https://uipaas-assets.com/prod/npm/alilc/lowcode-engine/(.*)/dist/js/engine-core.js, http://localhost:5555/js/AliLowCodeEngine.js ], [ https://uipaas-assets.com/prod/npm/alilc/lowcode-engine/(.*)/dist/css/engine-core.css, http://localhost:5555/css/AliLowCodeEngine.css ], [ https?://uipaas-assets.com/prod/npm/alilc/lowcode-engine/(.*)/dist/js/react-simulator-renderer.js, http://localhost:5555/js/ReactSimulatorRenderer.js ], [ https?://uipaas-assets.com/prod/npm/alilc/lowcode-engine/(.*)/dist/css/react-simulator-renderer.css, http://localhost:5555/css/ReactSimulatorRenderer.css ] ] }四条规则覆盖了两类产物的 js/css 共四个文件线上资源正则匹配(.*)为任意版本段本地目标5555 端口对应子包engine-core.js/js/AliLowCodeEngine.jspackages/engine编辑器内核engine-core.css/css/AliLowCodeEngine.csspackages/enginereact-simulator-renderer.js/js/ReactSimulatorRenderer.jspackages/react-simulator-renderer模拟器渲染器react-simulator-renderer.css/css/ReactSimulatorRenderer.csspackages/react-simulator-renderer从 NPM 包与源码位置的对应关系文档docs/docs/guide/appendix/npms.md也可以印证alilc/lowcode-engine对应packages/engine、alilc/lowcode-react-simulator-renderer对应packages/react-simulator-renderer正好是代理规则所指向的两个产物。4.3 开始调试运行npm start确认 5555 端口的开发服务已就绪打开一个 DEMO 页面官方文档以低代码引擎在线 DEMO 为例开启代理规则后刷新页面即可在浏览器中调试本地源码。注意代理只对表格中列出的四个产物生效。如果你修改的是其他子包如插件、渲染器核心可能需要按同样方式补充代理规则或改用 DEMO 页面对应的本地联调方案。五、贡献文档5.1 本地运行文档站文档站是一个独立的 Docusaurus 2 站点源码位于 docs/ 目录。在仓库根目录lowcode-engine下执行cd docs npm start从 docs/package.json 可以看到start的实际命令是docusaurus start --host 0.0.0.0监听所有网卡方便局域网访问此外还有build、serve、clear、write-heading-ids等标准 Docusaurus 命令文档源文件即 docs/docs/ 下的 Markdown。5.2 维护方式官方文档列出的文档协作约定官方文档通过 GitHub 管理文档源官网文档与主仓库 develop 分支的 docs 目录保持同步每篇文档下方的编辑此页链接可直接定位到仓库中的对应源文件欢迎提交文档 PR文档 PR 同样计入贡献者贡献度统计文档同步到官方网站由官方人员操作如有需要可通过 issue 或贡献者群与相关人员沟通为提升阅读体验文档中的图片文件会定期转换成可信的 CDN 地址。从仓库实际结构看文档站通过 docs/config/sidebars.js、docs/config/navbar.js 组织导航并配有 docs/scripts/sync-oss.js 等同步脚本与上述定期转换图片地址、由官方同步上线的描述相互印证。5.3 文档格式官方文档建议文档编写参考中文技术写作规范chinese-copywriting-guidelines 所确立的准则如中英文之间留空格、标点使用等使用 VSCode 编辑文档的开发者可安装huacnlee.autocorrect扩展辅助文档 lint。仓库内现成的文档风格样例可直接参考如本指南所依据的 docs/docs/participate/index.md 及 docs/docs/participate/flow.md。六、贡献低代码引擎生态官方文档指引生态相关的 NPM 包与源码位置、以及脚手架开发与调试机制分别见NPM 包对应源码位置汇总低代码生态脚手架 调试机制以 docs/docs/guide/appendix/npms.md 为例它把生态包映射到具体仓库与目录本仓库lowcode-engine内可贡献的部分包括包名本仓库内源码路径alilc/lowcode-enginepackages/enginealilc/lowcode-designerpackages/designeralilc/lowcode-editor-corepackages/editor-corealilc/lowcode-editor-skeletonpackages/editor-skeletonalilc/lowcode-react-rendererpackages/react-rendereralilc/lowcode-react-simulator-rendererpackages/react-simulator-rendereralilc/lowcode-renderer-corepackages/renderer-corealilc/lowcode-plugin-designerpackages/plugin-designeralilc/lowcode-plugin-outline-panepackages/plugin-outline-panealilc/lowcode-types/alilc/lowcode-utils/alilc/lowcode-shellpackages/types / packages/utils / packages/shellalilc/lowcode-code-generatormodules/code-generatoralilc/lowcode-material-parsermodules/material-parser其余如数据源系列lowcode-datasource、插件系列lowcode-plugins、物料系列lowcode-materials位于独立仓库可对照上表在 docs/docs/guide/appendix/npms.md 中查证完整清单。七、发布与版本管理官方文档说明PR 被合并之后我们会尽快发布相关的正式版本或者 beta 版本。从仓库配置可以进一步理解发布机制当前统一版本号在 lerna.json 中维护version字段npmClient为 yarn根 package.json 提供了一组pub脚本均先执行watchdog:buildscripts/watchdog.js再调用lerna publish例如npm run pub发布 patch 正式版npm run pub:minor/npm run pub:major发布 minor / major 正式版npm run pub:preminor/npm run pub:prepatch/npm run pub:prerelease以--dist-tag beta --preid beta发布 beta 版本。这解释了正式版本或 beta 版本两种发布形态的落点lerna publish的 minor/major 对应正式版带pre*的脚本对应 beta 版。另外 lerna.json 的command.version.allowBranch限定了允许升版的分支master、main、release/、daily/、refactor/*command.publish.ignoreChanges配置了.md与测试目录的变更不触发发布。八、PR 提交注意事项官方文档列出的提交规范原文要点完整保留分支策略lowcode-engine 仓库建议从develop创建分支PR 指向develop分支其他生态仓库从main分支创建分支PR 指向main分支补充测试如果你修复了 bug 或者添加了代码而这些内容需要测试请添加测试确保测试通过确保通过测试套件文档原文为yarn test。仓库根 package.json 中test脚本定义为lerna run test --stream即在各子包内流式执行各自的test脚本另有test:snapshot用于快照测试签署 CLA请签订贡献者许可证协议Contributor License Agreement。如已签署仍被提示需要签署参见 常见问题解答 中的解决办法提交规范与代码风格仓库通过 husky 安装了pre-commitf2elint commit-file-scan与commit-msgf2elint commit-msg-scan钩子见根 package.json 的husky字段与 commitlint.config.js提交信息需符合约定式规范与 lerna.json 中conventionalCommits: true的约定一致。仓库还配有 docs/docs/participate/code-specification.md 代码规范与 CONTRIBUTOR.md 贡献者说明提交前可一并查阅。九、加入 Contributor 群与寻找可贡献任务官方文档给出的参与入口提交过 Bugfix 或 Feature 类 PR 的同学如有兴趣参与维护 LowCodeEngine可加入核心贡献者交流群。官方流程为先通过问卷申请填写后添加文档中注明的微信号注明 github id即可被拉入群如果不知道可以贡献什么可以到源码里搜TODO或FIXME找找新手建议从带有good first issue标签的 issue 列表开始里面有相对没那么笼统的漏洞是不错的起点。结合仓库实际找任务的两个抓手是在 packages/ 与 modules/ 源码中检索 TODO/FIXME关注各子包的测试目录如 packages/designer/tests、modules/code-generator/tests中的既有用例按同样方式补充新用例。十、完整上手清单速查步骤命令 / 操作依据1. 准备 Node 16推荐 nvmnvm install 16 nvm use 16环境要求与engines约束2. 克隆仓库git clone gitgithub.com:alibaba/lowcode-engine.git cd lowcode-engine官方起步命令3. 安装并构建npm install npm run setup根setup脚本清 lock →lerna clean→lerna bootstrap --force-local4. 起本地服务5555 端口npm start等价于lerna exec --scope alilc/lowcode-ignitor -- npm start5. 配置代理并打开 DEMOXSwitch 导入第四节 JSON 规则代理 4 个产物到 localhost:55556. 本地预览文档站cd docs npm startdocusaurus start --host 0.0.0.07. 提交前跑测试yarn test即lerna run test --streamPR 规范要求测试通过8. 按分支规范提 PRdevelop 仓库从 develop 分支发起分支与 CLA 要求至此从环境准备到 PR 提交的完整贡献链路即可在 lowcode-engine 仓库内闭环完成源码改动经 5555 端口代理实时验证文档改动经 Docusaurus 本地预览最终以符合分支与测试规范的 PR 合入develop等待官方发布正式版或 beta 版。【免费下载链接】lowcode-engineAn enterprise-class low-code technology stack with scale-out design / 一套面向扩展设计的企业级低代码技术体系项目地址: https://gitcode.com/GitHub_Trending/lo/lowcode-engine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考