企业官网建设流程全解析

1小时跑通 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 是一个开源的 AI + 无代码平台，用来快速搭建业务系统。这篇文章带你走完开发环境搭建：克隆源码、装依赖、跑起一个能调 API 的最小实例，再到数据库配置和断点调试，全程在本地终端完成。

先把工具链对齐：Node、Yarn 和那条不能跳过的 postinstall

装依赖之前先看版本。项目根目录 package.json 里写得很明确：engines要求 Node 不低于 18，volta字段则把团队实际使用的版本钉在了 20.16.0 和 Yarn 1.22。你本机只要 Node 20.x + Yarn 1.x 就没问题，Node 21、22 一般也能跑，但原生依赖偶尔会出幺蛾子，遇到问题先回退到 20。

node -v

确认版本后再动手：

git clone https://gitcode.com/GitHub_Trending/no/nocobase cd nocobase cp .env.example .env

第三条命令容易被忽略：整个仓库没有现成的.env，只有 .env.example 这份模板。后面所有示例程序都靠它拿数据库和端口配置，缺了它，启动会直接报错。模板里DB_DIALECT=postgres、APP_PORT=13000这些默认值你可以先不动。

⚠️ 这里有个坑：yarn install结束后会自动跑postinstall钩子，它会调用内部的nocobase-v1 postinstall做模块装配和共享包编译。装的时候别用--ignore-scripts，否则共享包没编译，后面会冒出一堆莫名其妙的模块缺失错误，排查半天发现是这一步省了。

yarn install

装完后你会发现根目录多出一批packages/下的构建产物，这是正常的——它是个 Yarn workspace 大仓库，核心包（packages/core/ 下的 server、database、resourcer、acl 等）都以源码形式挂在本地，不需要你手动编译。

选一条最省事的路：用 examples 跑通第一个可验证的实例

环境就绪后，先别急着啃完整平台。仓库的 examples/ 目录放着一批独立小应用，每个文件就是一个完整的Application，启动脚本run:example会加载你指定的那个文件并执行，同时从当前目录读取.env。

其中 examples/app/single-app.ts 是最小的一个：它注册了一个名为test的资源，list动作直接返回一段字符串。启动它：

yarn run:example app/single-app start

控制台出现监听信息后，验证接口是否真的活着：

curl http://localhost:13000/api/test:list

如果终端打出test list，恭喜，链路已经通了：服务起来、资源路由生效、ACL 没有拦住你。

接下来如果你要改的是带 UI 的完整平台（界面、插件、权限那一套），换一条命令：

yarn dev

它会同时起客户端构建和后端服务，客户端改动热更新、后端源码改动自动重启，然后浏览器打开http://localhost:13000/就能看到界面。两条路的区别一句话总结：examples 用来验证"代码逻辑对不对"，yarn dev用来改"产品本身"。

数据层怎么接：方言、sqlite 捷径和 Migration 验证表结构

跑通实例后你大概会好奇：数据存哪了？看 examples/app/single-app.ts 的启动配置就明白——数据库连接参数（方言、主机、端口、库名、账号）全部从环境变量读，也就是你那份.env：

database: { dialect: process.env.DB_DIALECT, storage: process.env.DB_STORAGE, // 其余 host/port/user/password 同样来自 .env }

方言怎么选取决于你的目的。默认DB_DIALECT=postgres要连真实 PostgreSQL 服务；只想本地体验、不想起任何数据库进程，把.env里的方言改成sqlite并给DB_STORAGE指定文件路径（形如storage/db/nocobase.sqlite）即可，mysql、mariadb 同理，改方言加对应连接信息就行。另外注意single-app每次启动都会生成一个随机表前缀，两次运行互不干扰，做临时实验正好，但别指望重启后数据还在。

真正持久化地建表要靠 Migration。examples/app/migrations/add-migration.ts 里的MyMigration类实现up()（建一张test表）和down()（删掉它），执行方式是把migrator up/migrator down当参数传给run:example：

yarn run:example app/migrations/add-migration migrator up

跑完之后用数据库客户端确认test表存在，再执行down看到表消失，这一来一回就是迁移系统的完整闭环。

让代码"改得起来、查得起来"：请求链路与热重载

实例跑起来只是起点，能改起来才算搭好了开发环境。先花一分钟理解一次请求的走向，后面排查问题快很多：URL 里的/api是 resourcer 的统一前缀，test是资源名，list是动作名；请求进来会先过app.use注册的全局中间件和 ACL 权限检查，再落到动作函数里，函数里通过ctx.db访问数据库、ctx.i18n取多语言文案。examples 目录里 ctx.db.ts、acl.ts 这些文件分别演示了各环节的写法，遇到不懂的概念可以按图索骥。

到这一步，改代码就有两种姿势：

• examples 场景：它是独立脚本，改完single-app.ts里list的返回值，重跑一次run:example，curl验证新值是否返回。
• 完整平台场景：yarn dev本身就是热重载模式，直接进 packages/core/ 或 packages/plugins/ 打断点。IDE 的调试配置只需指定 Node 入口指向 dev 脚本，启动后在源码里设断点，用浏览器触发对应界面操作，请求就会停在断点上，你可以在调试控制台里直接求值ctx，看整个请求上下文长什么样。

💡 一个省时间的习惯：日志开关（DB_LOGGING=on打印 SQL、DEBUG 变量控制内部日志粒度）都藏在.env和 packages/logger/ 里，具体变量名该以你所用版本的源码为准，查一下再配，比背下来靠谱。

卡住了怎么办：四个高频坑的处理办法

最后把实际会踩的坑集中说一遍，省得你卡在一个点上耗半小时。

缺.env。症状是run:example一启动就报数据库或配置错误。原因很简单：tsx 只从当前工作目录读.env，没有就不存在任何配置。解法前面说过：cp .env.example .env再按需填库。

Node 版本不达标。安装阶段就炸，典型是原生依赖编译失败。用node -v确认不低于 18，推荐 20；有 nvm 的话nvm use 20切换。

端口 13000 被占。启动时报EADDRINUSE，要么lsof -i :13000找到占用进程停掉，要么在.env里改APP_PORT。

依赖冲突。项目根package.json的resolutions字段锁死了 React 18、antd 5 等一批关键版本，手动改子包依赖基本是徒劳，构建报类型或版本冲突时优先回退手动改动，从根目录重新yarn install。如果 node_modules 彻底乱了，删掉重装比逐条排查快得多。

环境到这里就算真正搭好了：能跑、能改、能查。想继续深入插件开发和客户端架构，官方文档入口是 docs.nocobase.com，仓库内 examples/index.md 的示例清单也值得留作常备手册。

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