NocoBase 开发环境搭建实战：从源码跑通到热更新调好
【免费下载链接】nocobaseNocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase
NocoBase 开发环境搭建的核心其实就是两件事：从源码跑起最小示例，再让完整 monorepo 的热更新转起来。假如你想写一个自定义插件、改完代码立刻看到效果，打开终端，跟着这篇文章敲命令就行。
🚀 5 分钟跑通最小开发环境
目标只有一个：让终端不再神秘。先不碰完整应用，我们把最小示例跑起来，看到 API 真实返回数据，你对项目的感觉就有了。
先拉代码并安装全部依赖：
git clone https://gitcode.com/GitHub_Trending/no/nocobase cd nocobase yarn install第二条命令比看起来重：NocoBase 是 monorepo，yarn install会顺带执行postinstall，把packages/下所有本地包互相关联进node_modules，首次跑需要几分钟。代码主要分两块：packages/core/放 server、database、权限控制（ACL，访问控制列表）等核心件，packages/plugins/放全部功能插件。示例不依赖这两块的编译产物，所以启动飞快——这也是我们先用示例热身的原因。
💡 提示：安装跑到一半别按 Ctrl+C，关联阶段中断是后面各种玄学报错的常见来源。
版本要求看这张表，不用纠结太多：
| 项目 | 推荐值 | 为什么 |
|---|---|---|
| Node.js | 20.x（项目锁定 20.16） | package.json声明>=18，但volta字段锁定 20.16.0，跟锁走最稳 |
| yarn | 1.22 | 项目用 yarn 1 classic，packageManager字段已固定 |
| 数据库 | SQLite（零配置） | 示例默认即可运行，之后要切换数据库方言再改 |
然后启动最小示例，并用一个请求验证：
yarn run:example app/single-app start # 启动完成后，另开一个终端执行： curl http://localhost:13000/api/test:list第一条命令跑的是 examples/app/single-app.ts：一个最精简的Application实例，只注册了一个test资源。第二条命令用来验证接口活着，看到返回test list，环境就算通了。
按需深入：三件你大概率要做的事
改完代码用热更新立刻看到效果
动核心代码或写插件（真正的插件开发配置场景），就用 monorepo 的开发模式：
yarn dev # 前后端一起，改动即热更 yarn dev-server # 只起后端，适合调 APIyarn dev会同时起前端编译和服务端监听，保存文件刷新浏览器即可。只写了前端组件可以加--client，只写了接口就用yarn dev-server，起需要的就行，省时间。
切换数据库方言的最小改动
配置入口是 examples/app/single-app.ts 里的database对象，每个字段都从环境变量读取，改连接参数不用碰代码：
| 环境变量 | 含义 | 示例值 |
|---|---|---|
DB_DIALECT | 数据库方言 | postgres/mysql/sqlite/mariadb |
DB_HOST/DB_PORT | 主机与端口 | 127.0.0.1/5432 |
DB_USER/DB_PASSWORD | 用户名与密码 | 按你的实例填 |
DB_DATABASE | 库名 | nocobase |
DB_STORAGE | SQLite 文件路径 | storage/db/nocodb.db |
DB_LOGGING | 是否打印 SQL | on |
给示例接上远程实例，这样启动：
DB_DIALECT=postgres DB_HOST=127.0.0.1 DB_PORT=5432 \ DB_USER=postgres DB_PASSWORD=secret DB_DATABASE=nocodb \ yarn run:example app/single-app start💡 提示：
dialect必须写小写官方名，大小写或拼写错误会直接起不来；想跑完整应用而不是示例，改 docker/docker-compose.yml 里的连接信息即可。
打开调试开关：断点、日志与 inspect 端口
最常用两个开关：Node 的 inspect 端口挂断点，DB_LOGGING=on打印全部 SQL。
NODE_OPTIONS="--inspect=9229" yarn run:example app/single-app start # 浏览器打开 chrome://inspect，挂上该进程即可打断点如果你用新版 CLI（nb），它直接提供了nb source dev --inspect 9229，少一步。排查数据问题再叠加DB_LOGGING=on，终端就能看到每个请求实际执行的 SQL，这就是 90% 场景够用的调试日志开关。
你大概率会踩的 3 个坑
坑都不致命，但都会卡住人。下面三个出现频率最高：
坑一：装依赖或构建时满屏报错
- 症状：
yarn install或yarn dev直接报错，esbuild 相关的平台错误最典型 - 原因：项目锁定 Node 20.16（
volta字段），Node 22 或 18 都可能水土不服 - 解法：
nvm use 20后重装依赖
坑二：yarn dev第一次启动页面白屏，像卡死
- 症状：启动后浏览器长时间白屏
- 原因：首次要把 monorepo 里所有前端产物编译一遍，等几分钟是正常的
- 解法：等终端编译完成；若报错，换
yarn dev:umi（切换到 umi 构建链的备选方案）
坑三：改了插件配置，页面还是老行为
- 症状：新增本地包或改了插件依赖后，页面表现没变化
- 原因：新增包要重新关联，部分配置变更需要 dev server 重启才生效
- 解法：Ctrl+C 后重跑
yarn dev；新增过包就先执行yarn install
💡 提示：三个坑的自查顺序一致——先查 Node 版本，再想是不是首次编译没等完，最后再重启，基本能覆盖九成问题。
🧭 接下来去哪看
环境跑通之后，想深入时认准这几个位置就够了：
- examples/：single-app、multi-app、迁移脚本等最小示例，想手写资源、action 或数据库迁移时先看这里
- docs/docs/cn/plugin-development/write-your-first-plugin.md：写第一个插件前先看这个
- docs/docs/cn/development/：开发指南总览，覆盖插件、FlowEngine、RunJS，计划扩展某类功能时看
- packages/core/：server、database、acl 等核心模块源码，想搞懂底层或提 PR 时看
- docker/docker-compose.yml：一键完整实例，想验收真实应用形态时用
【免费下载链接】nocobaseNocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
