Skip to main content

​
先决条件

  • Node.js 24+ — 在此下载
  • Yarn 4 — 通过 Corepack 随 Node.js 提供。 启用它：corepack enable
  • Docker — 在此下载。 运行本地 Twenty 服务器所需。 如果你已经在其他地方运行了 Twenty，请跳过。
构建一个 Twenty 应用包含三个阶段。 脚手架工具将它们合并为一个理想路径的命令，但每个阶段都是独立的概念——当出现问题时，知道自己处于哪个阶段可以指明需要修复什么。
阶段你要做什么工具结果
1. 脚手架生成应用的源代码npx create-twenty-app磁盘上的一个 TypeScript 项目
2. 运行服务器启动一个 Twenty 服务器以进行同步Docker + yarn twenty server一个正在运行的 Twenty 实例
3. 同步将你的代码实时同步到服务器yarn twenty dev你的更改会出现在 UI 中

​
阶段 1 — 搭建项目脚手架

从模板创建一个新应用： 
npx create-twenty-app@latest my-twenty-app
系统会提示你输入名称和描述——按下 Enter 采用默认值。 这将在 my-twenty-app/ 中生成一个 TypeScript 项目，包含一个入门版的 application-config.ts、一个默认角色、一个 CI 工作流，以及一个集成测试。 完成此阶段后： 你的机器上已有该应用的源代码。 它还未运行——那是第 2 阶段的内容。

​
阶段 2 — 运行本地 Twenty 服务器

你的应用需要一个 Twenty 服务器来进行同步。 该服务器是一个完整的 Twenty 实例——包含 UI、GraphQL API、PostgreSQL——在本地的 Docker 中运行。 你的本地代码会将其定义上传到该服务器，从而使其显示在 UI 中。 脚手架工具会为你提供启动它的选项：
是否要设置本地 Twenty 实例？
  • 是（推荐） — 将拉取 twentycrm/twenty-app-dev Docker 镜像，并在端口 2020 上启动它。 请先确保 Docker 正在运行。
  • 否 — 如果你已经有一个想要连接的 Twenty 服务器，请选择此项。 你可以稍后通过 yarn twenty remote add 将其连接起来。
是否启动本地实例？
服务器启动后，浏览器会打开登录页面。 使用预置的演示账户：
  • 邮箱： tim@apple.dev
  • 密码： tim@apple.dev
Twenty 登录界面
在下一屏点击 Authorize —— 这将授予 CLI 访问你工作区的权限。
Twenty CLI 授权界面
你的终端会确认一切已就绪。
应用脚手架创建成功
完成此阶段后： 你在 http://localhost:2020 上拥有一个正在运行的 Twenty 服务器，且你的 CLI 已获授权可与其同步。
如果未安装或未运行 Docker，脚手架工具会告诉你在所用操作系统上正确的启动命令。 Docker 启动后，你可以通过 yarn twenty server start 继续——无需重新生成脚手架。

​
阶段 3 — 同步你的更改

这是你大部分时间所处的内循环。 
cd my-twenty-app
yarn twenty dev
它会监视 src/，在每次更改时重新构建，并将结果同步到服务器。 编辑文件、保存，服务器会在一秒内反映出更改。 你会在终端中看到一个实时状态面板。 如需更详细的输出（构建日志、同步请求、错误跟踪），请添加 --verbose。
开发模式终端输出
打开 http://localhost:2020/settings/applications#developer。 你应当在 你的应用 下看到你的应用。
“你的应用”列表显示 My twenty app
点击 My twenty app 查看其应用注册——一条用于描述你的应用（名称、标识符、OAuth 凭据、来源）的服务器级记录。 同一服务器上的多个工作区可以安装同一个注册项。
应用注册详情
点击 查看已安装的应用 以查看工作区安装项。 关于 选项卡显示版本和管理选项。
已安装的应用
完成此阶段后： 你拥有一个实时的开发循环。 编辑 src/ 中的任意文件，更改会显示在 UI 中。

​
用于 CI 和脚本的一次性同步

传入 --once 以执行一次构建与同步后退出——相同的流水线，无文件监视器： 
yarn twenty dev --once
命令行为适用场景
yarn twenty dev监视并在每次更改时重新同步。 持续运行，直到你将其停止。交互式本地开发。
yarn twenty dev --once单次构建与同步，成功时以 0 退出，失败时以 1 退出。CI、pre-commit 钩子、AI 代理、脚本化工作流。
两种模式都需要处于开发模式的服务器和已认证的远程。
开发模式仅适用于以开发模式运行的 Twenty 实例（NODE_ENV=development）。 生产实例会拒绝开发同步请求——请使用 yarn twenty deploy 部署到生产服务器。 参见发布应用。

​
你可以构建的内容

应用由实体组成——每个实体定义为一个包含单一 export default 的 TypeScript 文件：
实体作用
对象与字段自定义数据模型（明信片、发票等） 带有类型化字段
逻辑函数由 HTTP 路由、cron 调度或数据库事件触发的服务端 TypeScript
前端组件在 Twenty 的 UI 内渲染的 React 组件（侧边面板、小部件、命令菜单）
技能与智能体AI 能力——可复用的指令和自主助手
视图与导航预配置的列表视图和侧边栏菜单项
页面布局带有选项卡和小部件的自定义记录详情页
完整参考：构建应用。

​
项目结构

my-twenty-app/
  package.json
  src/
    application-config.ts                   # Required — your app's entry point
    default-role.ts                         # Permissions for logic functions
    constants/
      universal-identifiers.ts              # Auto-generated UUIDs and metadata
    __tests__/
      setup-test.ts
      app-install.integration-test.ts
  .github/workflows/ci.yml                  # GitHub Actions
  public/                                   # Static assets
  vitest.config.ts                          # Test runner config
  tsconfig.json, tsconfig.spec.json
  .nvmrc, .yarnrc.yml, .oxlintrc.json
  README.md, LLMS.md
文件 / 文件夹目的
src/application-config.ts必需。 应用的主配置文件。
src/default-role.ts默认角色，用于控制你的逻辑函数可访问的内容。
src/constants/universal-identifiers.ts自动生成的 UUID 和元数据（显示名称、描述）。
src/__tests__/集成测试（设置 + 示例测试）。
public/随应用一起提供的静态资源（图像、字体）。

​
从示例开始

使用 --example 从一个更完整的项目开始（自定义对象、字段、逻辑函数、前端组件）： 
npx create-twenty-app@latest my-twenty-app --example postcard
示例位于 twenty-apps/examples。 你也可以使用 yarn twenty add 为现有项目生成单个实体的脚手架——参见构建应用。

​
管理本地服务器

使用 yarn twenty server 控制本地的 Twenty 容器：
命令作用
yarn twenty server start启动服务器（按需拉取镜像）
yarn twenty server start --port 3030在自定义端口启动
yarn twenty server stop停止服务器（保留数据）
yarn twenty server status显示 URL、版本和登录凭据
yarn twenty server logs流式输出服务器日志
yarn twenty server reset清空数据并全新开始
yarn twenty server upgrade拉取最新的 twenty-app-dev 镜像
yarn twenty server upgrade 2.2.0升级到指定版本
数据在重启后会保留，存储于两个 Docker 卷中（twenty-app-dev-data 用于 PostgreSQL，twenty-app-dev-storage 用于文件）。 使用 reset 清空所有内容。

​
升级服务器镜像

yarn twenty server upgrade 将拉取最新镜像、比较摘要，并且仅在确有变更时才重新创建容器。 数据卷将被保留——只会替换容器。 如果已拉取新镜像且容器正在运行，升级会自动启动一个新容器；之后运行 yarn twenty server start 以等待其变为健康状态。 
yarn twenty server upgrade            # Latest
yarn twenty server upgrade 2.2.0      # Specific version
使用 yarn twenty server status 验证正在运行的版本（它会显示写入容器的 APP_VERSION）。

​
运行并行测试实例

向任意 server 命令传递 --test 以管理第二个、完全隔离的实例——这有助于在不影响主开发数据的情况下进行集成测试或试验：
命令作用
yarn twenty server start --test启动测试实例 (默认端口为 2021)
yarn twenty server stop --test停止它
yarn twenty server status --test显示其状态
yarn twenty server logs --test流式输出其日志
yarn twenty server reset --test清空其数据
yarn twenty server upgrade --test升级其镜像
测试实例有其自己的容器（twenty-app-dev-test）、卷（twenty-app-dev-test-data、twenty-app-dev-test-storage）和配置——它可与你的主实例并行运行且不会发生冲突。 将 --test 与 --port 组合使用以覆盖 2021 端口。

​
手动设置（不使用脚手架）

如果你要将 SDK 添加到现有项目中，可跳过脚手架： 
yarn add twenty-sdk twenty-client-sdk
在 package.json 中添加该脚本： 
{
  "scripts": {
    "twenty": "twenty"
  }
}
现在你可以运行 yarn twenty dev、yarn twenty server start，以及其他命令。
不要全局安装 twenty-sdk —— 在每个项目中固定其版本，使每个应用都使用各自的版本。

​
故障排除

  • Docker 错误 — 在运行 yarn twenty server start 之前，请确保 Docker Desktop（或守护进程）已在运行。 错误消息会显示适用于你的操作系统的正确启动命令。
  • Node 版本不正确 — 需要 24+。 使用 node -v 检查。
  • 缺少 Yarn 4 — 运行 corepack enable。
  • 依赖损坏 — rm -rf node_modules && yarn install。
卡住了吗？ 在 Twenty 的 Discord 上提问。