如何 20 分钟本地跑通 NocoBase：一份从零到上线的开发环境搭建指南-平芜编程栈

如何 20 分钟本地跑通 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 与无代码能力的开源平台，让你少写代码也能搭建企业级业务系统。下面按"先跑起来、再接数据、再扩展功能、最后上线自查"四条主线，带你 NocoBase 快速上手，一次搭好开发环境。

先让 NocoBase 在本地跑起来

开发 NocoBase 只需要源码和 Yarn。先把仓库克隆到本地：

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

克隆完成后，安装全部依赖并构建项目，这两条命令可以直接复制执行：

yarn install yarn build

💡 如果你只改前端，可以用yarn build:client-v2单独构建客户端，迭代速度会明显快一些。

构建完成后启动开发服务器：

yarn dev

执行后前后端服务会一并拉起，浏览器打开http://localhost:13000就能看到运行中的界面。到这里，开发环境就已经就绪了。

核心代码位于 packages/core/ 目录，包含权限控制、数据操作、应用管理等关键模块。这种松耦合的模块化设计，意味着你日后查阅源码时能快速定位到对应能力所在的包，不用通读整个仓库。

选对数据库：SQLite 还是 PostgreSQL

NocoBase 数据库配置的关键在于选择方言。它支持 SQLite、MySQL、PostgreSQL 等多种数据库。💡 建议开发环境用 SQLite：无需额外安装数据库服务，最适合快速做原型；生产环境换用 PostgreSQL 或 MySQL，性能和可靠性更好。

初始化应用时指定方言与连接参数即可，下面是一个连接 PostgreSQL 的示例：

const app = new Application({ database: { dialect: 'postgres', host: 'localhost', port: 5432, username: 'your_username', password: 'your_password', database: 'nocobase_dev' } });

⚠️ 连不上时，先确认数据库服务是否启动、连接参数是否正确。对 PostgreSQL 可以用这条命令验证连通性：

psql -h localhost -p 5432 -U your_username -d nocobase_dev

内部数据库理顺之后，还可以接入外部数据源：在集合管理器中选择"连接外部数据"模板，指定对应的数据库服务器，就能把现有业务系统的数据整合进来，实现跨系统的数据打通。

数据建模是无代码开发平台的核心能力。NocoBase 支持一对一、一对多、多对多三种关联，全部通过可视化界面配置：一对多关系在 Students 集合中放置外键字段 Class ID 即可建立；多对多关系则通过中间表 Students Courses 连接两个集合，避免手动维护关联字段。

对于频繁改动表结构的项目，建议用迁移脚本把结构变化纳入版本控制，保证团队成员的数据库状态一致：

class AddUserProfileMigration extends Migration { async up() { await this.queryInterface.addColumn('users', 'profile', { type: DataTypes.JSON, allowNull: true }); } }

给项目装上第一个插件

插件系统是 NocoBase 扩展性的核心。plugins/ 目录下提供了从 AI 功能到工作流引擎的丰富插件，每个插件都可以独立开发、测试和部署。NocoBase 插件开发的基本骨架如下，在 load 方法中注册一个名为 my_collection 的集合：

export default class MyPlugin extends Plugin { async load() { // 插件加载逻辑 this.app.collectionManager.defineCollection({ name: 'my_collection', fields: [ { type: 'string', name: 'title' } ] }); } }

开发完成后，通过 NocoBase 的命令行工具安装并激活插件即可。

除了插件，你还可以开发自定义中间件来扩展 HTTP 请求处理：在中间件里于调用 next 前后分别记录请求的方法与地址，就能方便地叠加认证、日志记录、性能监控等企业级能力。排查问题时可以设置process.env.DEBUG = 'nocobase:*'再启动应用，所有相关日志都会输出到控制台，帮助你理解系统运行状态。

上线前自查：构建、缓存与排障

生产部署时用专门的构建命令产出更小的包，代码压缩、Tree Shaking 等优化会显著减少最终体积：

yarn build --production

查询压力大的场景，可以按需注册缓存策略，例如通过app.cacheManager.registerStrategy('redis', {...})接入 Redis 缓存，大批量查询的响应速度会明显提升。日志方面，用app.logger.level = 'info'调整输出级别，并配置文件输出到logs/app.log，确保线上问题可回溯。

遇到下面两类问题，优先按对应方式处理：