NocoBase 本地开发环境如何从零跑通：5 步克隆、编译、启动并验证接口

NocoBase 本地开发环境如何从零跑通：5 步克隆、编译、启动并验证接口

【免费下载链接】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 的仓库拉下来，怎么最快让它在你自己电脑上转起来？这篇文章带你走一遍最短路径：装依赖、起开发服务、再改一个最小示例应用加上数据库，最后用一个 curl 请求证明"它真的在运行"。全程不需要先装数据库，跑完你会看到一条来自本地服务的真实响应。

先确认两个版本：Node 和 Yarn

这一步别跳过，版本不对后面全是坑。

依据仓库里的两份配置：

• package.json 中"engines": { "node": ">=18" }，并且用 volta 字段把版本钉死在node 20.16.0、yarn 1.22.19
• Dockerfile 官方镜像用的是node:22-bookworm

所以给你一条稳妥的结论：Node 用 20 LTS（或 22），包管理器用 Yarn 1.x。不要上 pnpm 或 npm 装这个仓库，它是 yarn workspaces 结构（packages/*/*多级工作区）。

node -v # 应输出 v20.x 或 v22.x，低于 18 请换版本 yarn -v # 应输出 1.22.x；没有就 npm install -g yarn

3 条命令克隆并装好依赖

# 克隆仓库（仓库地址就是这一个） git clone https://gitcode.com/GitHub_Trending/no/nocobase cd nocobase # 装依赖，仓库共几十个 workspace 子包，耐心等待 yarn install

✅ 成功标志：yarn install最后打印Done in ...。

两个常见卡点先说清楚：

• ⚠️yarn install会触发根目录的postinstall脚本（nocobase-v1 postinstall），装到一半"卡住"其实是它在跑，不是死机。
• 如果你看到某个原生模块（node-gyp 相关）编译失败，基本是 Node 版本过新或过老，先回到上一节对齐版本，再删掉node_modules重装。

一条命令起开发服务，用 curl 验证真的启动了

装完依赖，直接进开发模式：

# 启动带热更新的开发服务（前端用 rsbuild 构建） yarn dev

跑完等几十秒，终端里出现服务监听地址（默认 13000 端口）就是起来了。然后开另一个终端：

# 请求一条接口，验证服务真的能响应 curl http://localhost:13000/api/app:info

✅ 成功标志：返回一段 JSON。如果返回 JSON 里带401之类的鉴权信息，也算成功——说明服务和接口框架都在工作，只是这个接口要求登录。真正失败的表现是Connection refused，那说明进程根本没监听端口，回到终端看报错。

想要只热更后端、不动前端，就换yarn dev-server；想打生产构建产物，用yarn build，然后yarn start以生产模式跑。

换个最小示例应用，把数据库也带上

内置首页已经能看了，但开发者的日常是写自己的代码。仓库里放了一个最小可运行应用，就是为这个场景准备的：

# 启动 examples 目录下的单应用示例 yarn run:example app/single-app start

# 访问示例自带的 test 资源 curl http://localhost:13000/api/test:list

✅ 成功标志：响应体是字符串test list。看到它，说明"你的代码 → 服务 → 接口"这条链路完整通了。

数据库怎么接？示例从环境变量读配置，完整写法见 examples/app/single-app.ts，核心字段是这几个：

database: { dialect: process.env.DB_DIALECT, // 方言：sqlite / mysql / postgres storage: process.env.DB_STORAGE, // sqlite 时填 .db 文件路径 // 其余 username / password / host / port 按方言按需设置 }

本地想最快跑通，选 SQLite 就对了——不用起任何数据库进程：

# 用环境变量告诉示例用哪个库，然后重新启动 DB_DIALECT=sqlite DB_STORAGE=./storage/dev.db yarn run:example app/single-app start

需要真正操作表结构时，仓库提供了迁移示例：

# 跑 examples 里的建表/删表演示迁移 yarn run:example app/migrations/add-migration migrator up

卡住了？按这份清单自查

Q：yarn install一直报网络错误或超时？这个仓库依赖量很大（几百个子包）。先换国内镜像源再试：yarn config set registry https://registry.npmmirror.com。仓库根目录还有个cnpm-sync.js辅助脚本，装不上时可以在文档里查它的用法。

Q：改了代码没生效，配置不生效？先确认你启动的方式。yarn dev是热更新模式，改后端 TS 文件保存即重编；如果你用的是yarn start（生产模式），改任何源码都不会生效，必须yarn build重新打包。

Q：端口 13000 被占用？curl报ECONNREFUSED多半是上次进程没退干净。先Ctrl+C停掉旧进程，或换一个端口：启动时通过环境变量调整（examples/app/single-app.ts里没写死端口，以终端实际输出为准）。

Q：我想写自己的插件，代码放哪？新插件统一放在packages/plugins/@nocobase/plugin-<你的插件名>/目录下，直接复制现有插件的目录结构改造即可，仓库的 AGENTS.md 明确写了"复用现有脚手架，不要自创新布局"。仓库中未找到一键生成插件的独立脚本命令，可参考官方文档的插件开发章节。

Q：前端页面白屏？看浏览器控制台的网络请求，接口 404 通常是服务没起完（yarn dev首次编译前端需要更久）；接口 401 则是正常鉴权拦截，用登录接口或数据库里现成的管理员账号登录即可。

跑通之后，你可以顺着本地界面进入数据建模，效果类似官方文档里的这个界面（表间关系配置）：

关键步骤速查表

【免费下载链接】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