开始使用 - Clara Documentation

什么是应用？

应用可通过自定义对象、字段、逻辑函数、前端组件、AI 技能等来扩展 Twenty——全部以代码进行管理。无需通过 UI 配置所有内容，你可以用 TypeScript 定义数据模型和逻辑，并将其部署到一个或多个工作空间。

先决条件

在开始之前，请确保你的机器已安装以下内容：

Node.js 24+ — 在此下载
Yarn 4 — 通过 Corepack 随 Node.js 提供。通过运行 corepack enable 启用它
Docker — 在此下载。运行本地 Twenty 实例所必需。如果你已经有一个正在运行的 Twenty 服务器，则不需要。

创建你的第一个应用

为你的应用创建脚手架

打开终端并运行：

npx create-twenty-app@latest my-twenty-app

系统会提示你为应用输入名称和描述。按下 Enter 接受默认值。这会创建一个名为 my-twenty-app 的新文件夹，其中包含你所需的一切。

设置本地 Twenty 实例

脚手架工具会询问：

是否要设置本地 Twenty 实例？

输入 yes（推荐）— 这将拉取 twenty-app-dev Docker 镜像，并在端口 2020 上启动本地 Twenty 服务器。继续之前，请确保 Docker 正在运行。
输入 no — 如果你已经有一个在本地运行的 Twenty 服务器，请选择此项。

登录你的工作区

接下来，将打开一个浏览器窗口，显示 Twenty 登录页面。使用预置的演示账户登录：

邮箱： tim@apple.dev
密码： tim@apple.dev

授权该应用

登录后，你会看到一个授权界面。这使你的应用可以与工作区交互。点击授权继续。

授权后，你的终端会确认一切已就绪。

开始开发

进入你的新应用文件夹并启动开发服务器：

cd my-twenty-app
yarn twenty dev

它会监听你的源文件，每次更改都会重建，并自动将你的应用同步到本地 Twenty 服务器。你应当在终端中看到一个实时状态面板。如需更详细的输出（构建日志、同步请求、错误跟踪），请使用 --verbose 标志：

yarn twenty dev --verbose

开发模式仅适用于以开发模式运行的 Twenty 实例（NODE_ENV=development）。生产实例会拒绝开发同步请求。使用 yarn twenty deploy 部署到生产服务器——详见发布应用。

使用 `yarn twenty dev --once` 进行一次性同步

如果不希望有监视器在后台运行（例如在 CI 流水线、git 钩子或脚本化工作流中），请传入 --once 标志。它运行与 yarn twenty dev 相同的流水线 — 构建清单、打包文件、上传、同步、重新生成类型化 API 客户端 — 但会在同步完成后立即退出：

yarn twenty dev --once

命令	行为	适用场景
`yarn twenty dev`	监视你的源文件，并在每次更改时重新同步。会持续运行，直到你停止它。	交互式本地开发 — 你需要实时状态面板和即时反馈循环。
`yarn twenty dev --once`	执行一次构建与同步，然后在成功时以代码 `0` 退出，失败时以代码 `1` 退出。	脚本、CI、pre-commit 钩子、AI 代理，以及任何非交互式工作流。

两种模式都需要一个以开发模式运行的 Twenty 服务器和一个已认证的远程端 — 相同的先决条件同样适用。

在 Twenty 中查看你的应用

在浏览器中打开 http://localhost:2020/settings/applications#developer。前往 设置 > 应用，并选择 开发者 选项卡。你应当在 你的应用 下看到你的应用：

点击 My twenty app 打开其 应用注册。注册项是一个服务器级记录，用于描述你的应用——其名称、唯一标识符、OAuth 凭据以及来源（本地、npm 或 tarball）。它位于服务器上，而不在任何特定工作区内。当你将应用安装到工作区时，Twenty 会创建一个工作区范围的应用，指向该注册项。同一服务器上的多个工作区可以安装同一个注册项。

点击 查看已安装的应用 以查看已安装的应用。关于选项卡显示当前版本和管理选项：

切换到内容选项卡，以查看你的应用提供的全部内容——对象、字段、逻辑函数和智能体：

一切就绪！编辑 src/ 中的任意文件，更改会被自动检测到。

你可以构建的内容

应用由实体组成——每个实体定义为一个包含单一 export default 的 TypeScript 文件：

实体	作用
对象与字段	使用类型化字段定义自定义数据模型（如 Post Card、Invoice）
逻辑函数	由 HTTP 路由、cron 调度或数据库事件触发的服务端 TypeScript 函数
前端组件	在 Twenty 的 UI 内渲染的 React 组件（侧边面板、小部件、命令菜单）
技能与智能体	AI 能力——可复用的指令和自主助手
视图与导航	为你的对象预配置的列表视图和侧边栏菜单项
页面布局	带有选项卡和小部件的自定义记录详情页

前往构建应用，查看每种实体类型的详细指南。

项目结构

脚手架工具会生成以下文件结构：

my-twenty-app/
  package.json
  yarn.lock
  .gitignore
  .nvmrc
  .yarnrc.yml
  .oxlintrc.json
  tsconfig.json
  tsconfig.spec.json                          # TypeScript config for tests
  vitest.config.ts                            # Vitest test runner configuration
  LLMS.md
  README.md
  .github/
    └── workflows/
        └── ci.yml                            # GitHub Actions CI workflow
  public/                                     # Public assets (images, fonts, etc.)
  src/
  ├── application-config.ts                   # Required — main application configuration
  ├── default-role.ts                         # Default role for logic functions
  ├── constants/
  │   └── universal-identifiers.ts            # Auto-generated UUIDs and app metadata
  └── __tests__/
      ├── setup-test.ts                       # Test setup (server health check, config)
      └── app-install.integration-test.ts     # Integration test

从示例开始

若要从一个更完整的示例开始（包含自定义对象、字段、逻辑函数、前端组件等），请使用 --example 标志：

npx create-twenty-app@latest my-twenty-app --example postcard

示例来自 GitHub 上的 twenty-apps/examples 目录。你也可以使用 yarn twenty add 为现有项目生成单个实体的脚手架（参见构建应用）。

关键文件

文件 / 文件夹	目的
`package.json`	声明应用的名称、版本和依赖。包含一个 `twenty` 脚本，因此你可以运行 `yarn twenty help` 查看所有命令。
`src/application-config.ts`	必需。应用的主配置文件。
`src/default-role.ts`	默认角色，用于控制你的逻辑函数可访问的内容。
`src/constants/universal-identifiers.ts`	自动生成的 UUID 和应用元数据（显示名称、描述）。
`src/__tests__/`	集成测试（设置 + 示例测试）。
`public/`	随应用一起提供的静态资源（图像、字体）。

本地开发服务器

脚手架工具已经为你启动了一个本地 Twenty 服务器。稍后要进行管理，请使用 yarn twenty server：

命令	描述
`yarn twenty server start`	启动本地服务器（按需拉取镜像）
`yarn twenty server start --port 3030`	在自定义端口启动
`yarn twenty server start --test`	在 2021 端口启动一个独立的测试实例
`yarn twenty server stop`	停止服务器（保留数据）
`yarn twenty server status`	显示服务器状态、URL 和凭据
`yarn twenty server logs`	流式输出服务器日志
`yarn twenty server logs --lines 100`	显示最近 100 行日志
`yarn twenty server reset`	删除所有数据并全新开始

数据在重启后会保留，存储于两个 Docker 卷中（twenty-app-dev-data 用于 PostgreSQL，twenty-app-dev-storage 用于文件）。使用 reset 清空所有内容并重新开始。

运行测试实例

向任何 server 命令传递 --test 以管理第二个、完全隔离的实例——这对于运行集成测试或在不影响主开发数据的情况下进行试验非常有用。

命令	描述
`yarn twenty server start --test`	启动测试实例 (默认端口为 2021)
`yarn twenty server stop --test`	停止测试实例
`yarn twenty server status --test`	显示测试实例状态、URL 和凭据
`yarn twenty server logs --test`	流式输出测试实例日志
`yarn twenty server reset --test`	清除测试数据并全新开始

测试实例在其独立的 Docker 容器 (twenty-app-dev-test) 中运行，配有专用的卷 (twenty-app-dev-test-data, twenty-app-dev-test-storage) 和配置，因此可以与主实例并行运行且不会发生冲突。将 --test 与 --port 一起使用以覆盖默认的 2021 端口。

服务器需要 Docker 处于运行状态。如果看到 “Docker not running” 错误，请确保 Docker Desktop（或 Docker 守护进程）已启动。

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

如果你不想使用 create-twenty-app，而是自行完成设置，可以分两步进行。 **1. 将 twenty-sdk 和 twenty-client-sdk 添加为依赖项：

yarn add twenty-sdk twenty-client-sdk

**2. 在你的 package.json 中添加一个 twenty 脚本：

{
  "scripts": {
    "twenty": "twenty"
  }
}

现在你可以运行 yarn twenty dev、yarn twenty help 以及所有其他命令。

不要全局安装 twenty-sdk。始终将其作为本地项目依赖使用，以便每个项目都能固定其自己的版本。

故障排除

如果遇到问题：

在使用本地实例启动脚手架工具之前，请确保Docker 已在运行。
请确保使用 Node.js 24+（运行 node -v 进行检查）。
请确保已启用 Corepack（corepack enable），以便可使用 Yarn 4。
如果依赖似乎有问题，尝试删除 node_modules 并重新运行 yarn install。

仍然遇到问题？在 Twenty 的 Discord 上寻求帮助。

​什么是应用？

​先决条件

​创建你的第一个应用

​为你的应用创建脚手架

​设置本地 Twenty 实例

​登录你的工作区

​授权该应用

​开始开发

​使用 yarn twenty dev --once 进行一次性同步

​在 Twenty 中查看你的应用

​你可以构建的内容

​项目结构

​从示例开始

​关键文件

​本地开发服务器

​运行测试实例

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

​故障排除

什么是应用？

先决条件

创建你的第一个应用

为你的应用创建脚手架

设置本地 Twenty 实例

登录你的工作区

授权该应用

开始开发

使用 `yarn twenty dev --once` 进行一次性同步

在 Twenty 中查看你的应用

你可以构建的内容

项目结构

从示例开始

关键文件

本地开发服务器

运行测试实例

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

故障排除