企业官网建设流程全解析

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 是一个把 AI 能力叠加在无代码界面上的开源平台。想给上游贡献代码、给自己的业务写插件做深度二开、或者怀疑数据链路有问题要往下层挖，你得站在源码上，而不是打包好的发行版。门槛不高：Node.js 20.x 是稳妥选择（仓库 engines 字段要求 18 及以上，volta 配置锁定 20.16.0），把仓库克隆下来就能开工：

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

依赖安装与开发态构建

依赖装好了，项目才算有呼吸。这一章按真实操作顺序走：装依赖、跑开发态构建，顺便建立目录的空间感。

yarn install

这个仓库是 yarn workspaces 结构的 monorepo（多包合一的仓库组织方式）：一次 install 会把所有核心包、插件包一起解析，装完还会自动触发 postinstall 脚本完成包之间的本地链接，不用你手动一个个软链。

yarn dev

yarn dev 启动的是 watch 构建（底层用 rsbuild），前后端文件一改就重新编译、热更新，适合边写边看。只想要一份产物、不需要监听，换用yarn build即可。

目录上只需要记两件事：核心运行时代码在 packages/core/，server、database、acl 都在里面；插件代码集中在 packages/plugins/。想加什么功能，先确认它归属哪个包，再动手翻代码，能省掉大量迷路时间。

数据库方言与迁移命令

应用能跑之后，下一个要回答的问题是：数据往哪儿存。NocoBase 统一从环境变量读取数据库连接参数，不用改任何代码。最直接的做法：把仓库根目录的 .env.example 复制成同目录下的 .env，再按注释填写。

DB_DIALECT=postgres # postgres | mysql | mariadb | kingbase DB_HOST=localhost DB_PORT=5432 DB_DATABASE=nocobase DB_USER=nocobase DB_PASSWORD=nocobase

方言（dialect，即数据库类型）是关键字段，它决定 ORM（对象关系映射，这里指 Sequelize）走哪套连接逻辑；其余几项就是地址、端口和凭据。连接池、SSL 这些进阶项，.env.example 里都留了现成注释，按需打开即可。

应用跑通后，经常会要加表、改字段。迁移脚本干的就是这件事：一段声明「怎么升级、怎么回滚」的代码，注册给应用后由迁移器执行，升级和回滚各走一遍。最小示例（摘自 examples/app/migrations/add-migration.ts）：

class MyMigration extends Migration { async up() { await this.queryInterface.createTable('test', { name: DataTypes.STRING }); } async down() { await this.queryInterface.dropTable('test'); } }

执行只需一条命令：

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

迁移跑完，表结构可以直接在后台的数据建模界面核对，关联字段的配置长这样：

启动验证与高频报错速查 🚀

数据层接上了，现在把应用真正拉起来，用一个接口确认它活着。

yarn run:example app/single-app start

这条命令用 examples/app/single-app.ts 里的单应用示例起一个最简应用，默认监听 13000 端口。起完用一条请求验证：

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

返回test list，说明从进程到路由的整条链路都通了。

调试不用动源码，走环境变量注入即可：LOGGER_LEVEL=debug打开详细日志，再加DB_LOGGING=on，控制台会打印每条实际执行的 SQL，排查数据问题特别顺手：

DB_LOGGING=on LOGGER_LEVEL=debug yarn run:example app/single-app start

⚠️ 三个高频坑，按「症状 → 原因 → 解法」过一遍：

1. yarn install 中途报错，提示 engine 不匹配或 gyp 构建失败原因：Node 版本太老，或镜像源配置不对，原生模块编译失败。 解法：切到 Node.js 20.x，删掉 node_modules 重新安装。
2. curl 连不上，提示 connection refused 或端口被占用原因：13000 被其他进程占了，或者应用还在启动中。 解法：把 .env 里的 APP_PORT 改成空闲端口，重启。
3. 页面能打开但接口一直报错，日志反复出现数据库连接失败原因：DB_DIALECT 和真实数据库对不上，比如写了 postgres 实际是 mysql；或者数据库服务根本没启动。 解法：对照 .env 逐项核对方言和端口，并先确认数据库服务在监听。

继续深入时的资源索引

主线走通了，后面想再往下挖，按需取用：

• 如果你要写插件 → 读 docs/docs/cn/plugin-development/ 目录下的文档，示例代码看 packages/plugins/@nocobase-example/
• 如果你要跑测试 → 后端用yarn test:server，前端用yarn test:client，两个脚本都定义在根目录 package.json 里
• 如果你要看官方构建与部署流程 → Dockerfile 里保留了完整的镜像构建过程
• 如果你要核对全量环境变量 → .env.example 每一项都有注释，集群模式、日志轮转都包含在内
• 如果你要更多可运行的小例子 → examples/ 下有 app、database、api-client 几个子目录，每个文件头部都写了运行步骤

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