---
title: 开始使用
description: 几分钟内创建你的第一个 Twenty 应用。
---

<Warning>
应用目前处于 Alpha 阶段。 该功能可用，但仍在演进中。
</Warning>

应用可通过自定义对象、字段、逻辑函数、AI 技能和 UI 组件来扩展 Twenty——全部以代码进行管理。

## 先决条件

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

* **Node.js 24+** — [在此下载](https://nodejs.org/)
* **Yarn 4** — 通过 Corepack 随 Node.js 提供。 通过运行 `corepack enable` 启用它
* **Docker** — [在此下载](https://www.docker.com/products/docker-desktop/)。 运行本地 Twenty 实例所必需。 如果你已经有一个正在运行的 Twenty 服务器，则不需要。

## 步骤 1：为你的应用创建脚手架

打开终端并运行：

```bash filename="Terminal"
npx create-twenty-app@latest my-twenty-app
```

系统会提示你为应用输入名称和描述。 按下 **Enter** 接受默认值。

这会创建一个名为 `my-twenty-app` 的新文件夹，其中包含你所需的一切。

<Note>
脚手架工具支持以下标志：

* `--minimal` — 仅创建必要文件，不包含示例（默认）
* `--exhaustive` — 创建所有示例实体
* `--name <name>` — 设置应用名称（跳过提示）
* `--display-name <displayName>` — 设置显示名称（跳过提示）
* `--description <description>` — 设置描述（跳过提示）
* `--skip-local-instance` — 跳过本地服务器设置提示
</Note>

## 步骤 2：设置本地 Twenty 实例

脚手架工具会询问：

> **是否要设置本地 Twenty 实例？**

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

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/start-instance.png" alt="是否启动本地实例？" />
</div>

## 步骤 3：登录你的工作区

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

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

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/login.png" alt="Twenty 登录界面" />
</div>

## 步骤 4：授权该应用

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

点击 **授权** 继续。

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/authorize.png" alt="Twenty CLI 授权界面" />
</div>

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

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/scaffolded.png" alt="应用脚手架创建成功" />
</div>

## 步骤 5：开始开发

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

```bash filename="Terminal"
cd my-twenty-app
yarn twenty dev
```

它会监听你的源文件，每次更改都会重建，并自动将你的应用同步到本地 Twenty 服务器。 你应当在终端中看到一个实时状态面板。

如需更详细的输出（构建日志、同步请求、错误跟踪），请使用 `--verbose` 标志：

```bash filename="Terminal"
yarn twenty dev --verbose
```

<Warning>
开发模式仅适用于以开发模式运行的 Twenty 实例（`NODE_ENV=development`）。 生产实例会拒绝开发同步请求。 使用 `yarn twenty deploy` 部署到生产服务器——详见[发布应用](/l/zh/developers/extend/apps/publishing)。
</Warning>

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/dev.jpg" alt="开发模式终端输出" />
</div>

## 步骤 6：在 Twenty 中查看你的应用

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

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/app-in-ui-1.png" alt="“你的应用”列表显示 My twenty app" />
</div>

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

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="应用注册详情" />
</div>

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

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="已安装的应用 — “关于”选项卡" />
</div>

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

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/app-in-ui-4.png" alt="已安装的应用 — “内容”选项卡" />
</div>

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

前往[构建应用](/l/zh/developers/extend/apps/building)，查看关于创建对象、逻辑函数、前端组件、技能等的详细指南。

---

## 项目结构

脚手架工具会生成以下文件结构（以 `--exhaustive` 模式展示，其中包含每种实体类型的示例）：

```text filename="my-twenty-app/"
my-twenty-app/
  package.json
  yarn.lock
  .gitignore
  .nvmrc
  .yarnrc.yml
  .yarn/
    install-state.gz
  .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
  ├── __tests__/
  │   ├── setup-test.ts                   # Test setup (server health check, config)
  │   └── app-install.integration-test.ts # Example integration test
  ├── roles/
  │   └── default-role.ts                 # Default role for logic functions
  ├── objects/
  │   └── example-object.ts               # Example custom object definition
  ├── fields/
  │   └── example-field.ts                # Example standalone field definition
  ├── logic-functions/
  │   ├── hello-world.ts                  # Example logic function
  │   ├── create-hello-world-company.ts   # Example logic function using CoreApiClient
  │   ├── pre-install.ts                  # Runs before installation
  │   └── post-install.ts                 # Runs after installation
  ├── front-components/
  │   └── hello-world.tsx                 # Example front component
  ├── page-layouts/
  │   └── example-record-page-layout.ts   # Example page layout with front component
  ├── views/
  │   └── example-view.ts                 # Example saved view definition
  ├── navigation-menu-items/
  │   └── example-navigation-menu-item.ts # Example sidebar navigation link
  ├── skills/
  │   └── example-skill.ts                # Example AI agent skill definition
  └── agents/
      └── example-agent.ts                # Example AI agent definition
```

默认情况下（`--minimal`），仅创建核心文件：`application-config.ts`、`roles/default-role.ts`、`logic-functions/pre-install.ts` 和 `logic-functions/post-install.ts`。 使用 `--exhaustive` 可包含上面展示的所有示例文件。

### 关键文件

| 文件 / 文件夹                     | 目的                                                                 |
| ---------------------------- | ------------------------------------------------------------------ |
| `package.json`               | 声明应用的名称、版本和依赖。 包含一个 `twenty` 脚本，因此你可以运行 `yarn twenty help` 查看所有命令。 |
| `src/application-config.ts`  | **必需。** 应用的主配置文件。                                                  |
| `src/roles/`                 | 定义角色，用于控制逻辑函数的访问权限。                                                |
| `src/logic-functions/`       | 由路由、cron 调度或数据库事件触发的服务端函数。                                         |
| `src/front-components/`      | 在 Twenty 的 UI 中渲染的 React 组件。                                       |
| `src/objects/`               | 用于扩展数据模型的自定义对象定义。                                                  |
| `src/fields/`                | 添加到现有对象的自定义字段。                                                     |
| `src/views/`                 | 已保存的视图配置。                                                          |
| `src/navigation-menu-items/` | 侧边栏导航中的自定义链接。                                                      |
| `src/skills/`                | 用于扩展 Twenty 的 AI 代理的技能.                                            |
| `src/agents/`                | 具有自定义提示词的 AI 智能体。                                                  |
| `src/page-layouts/`          | 记录视图的自定义页面布局。                                                      |
| `src/__tests__/`             | 集成测试（设置 + 示例测试）。                                                   |
| `public/`                    | 随应用一起提供的静态资源（图像、字体）。                                               |

## 管理远程

“远程”是指你的应用连接到的 Twenty 服务器。 在设置期间，脚手架工具会为你自动创建一个。 你可以随时添加更多远程或在它们之间切换。

```bash filename="Terminal"
# Add a new remote (opens a browser for OAuth login)
yarn twenty remote add

# Connect to a local Twenty server (auto-detects port 2020 or 3000)
yarn twenty remote add --local

# Add a remote non-interactively (useful for CI)
yarn twenty remote add --api-url https://your-twenty-server.com --api-key $TWENTY_API_KEY --as my-remote

# List all configured remotes
yarn twenty remote list

# Switch the active remote
yarn twenty remote switch <name>
```

你的凭据存储在 `~/.twenty/config.json` 中。

## 本地开发服务器（`yarn twenty server`）

CLI 可以管理在 Docker 中运行的本地 Twenty 服务器。 这与使用 `create-twenty-app` 搭建应用时自动启动的服务器相同，但你也可以手动管理它。

### 启动服务器

```bash filename="Terminal"
yarn twenty server start
```

这将拉取 `twentycrm/twenty-app-dev:latest` Docker 镜像（如果尚未存在），创建名为 `twenty-app-dev` 的容器，并在端口 **2020** 上启动它。 CLI 会等待服务器通过健康检查后再返回。

会创建两个 Docker 卷，以在重启之间持久化数据：

* `twenty-app-dev-data` — PostgreSQL 数据库
* `twenty-app-dev-storage` — 文件存储

如果端口 2020 已被占用，你可以在其他端口上启动：

```bash filename="Terminal"
yarn twenty server start --port 3030
```

CLI 会自动配置容器内部的 `NODE_PORT` 和 `SERVER_URL` 以匹配所选端口，从而使逻辑函数、OAuth 以及所有其他内部网络正常工作。

启动后，该服务器会在你的 CLI 配置中自动注册为 `local` 远程。

### 检查服务器状态

```bash filename="Terminal"
yarn twenty server status
```

显示服务器是否在运行、其 URL，以及默认登录凭据（`tim@apple.dev` / `tim@apple.dev`）。

### 查看服务器日志

```bash filename="Terminal"
yarn twenty server logs
```

持续输出容器日志。 使用 `--lines` 控制显示的最近日志行数：

```bash filename="Terminal"
yarn twenty server logs --lines 100
```

### 停止服务器

```bash filename="Terminal"
yarn twenty server stop
```

停止容器。 你的数据会保存在 Docker 卷中——下次 `start` 会从上次中断处继续。

### 重置服务器

```bash filename="Terminal"
yarn twenty server reset
```

移除容器并删除这两个 Docker 卷，清除所有数据。 下一次 `start` 会创建一个全新实例。

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

### 命令参考

| 命令                                     | 描述              |
| -------------------------------------- | --------------- |
| `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 logs --lines 100`  | 显示最近 100 行日志    |
| `yarn twenty server reset`             | 删除所有数据并全新开始     |

## 使用 GitHub Actions 进行 CI

脚手架工具会在 `.github/workflows/ci.yml` 生成一个开箱即用的 GitHub Actions 工作流。 它会在每次向 `main` 推送以及拉取请求上自动运行你的集成测试。

工作流：

1. 检出你的代码
2. 使用 `twentyhq/twenty/.github/actions/spawn-twenty-docker-image` 动作启动一个临时的 Twenty 服务器
3. 使用 `yarn install --immutable` 安装依赖
4. 运行 `yarn test`，并从该动作的输出中注入 `TWENTY_API_URL` 和 `TWENTY_API_KEY`

```yaml .github/workflows/ci.yml
name: CI

on:
  push:
    branches:
      - main
  pull_request: {}

env:
  TWENTY_VERSION: latest

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Spawn Twenty instance
        id: twenty
        uses: twentyhq/twenty/.github/actions/spawn-twenty-docker-image@main
        with:
          twenty-version: ${{ env.TWENTY_VERSION }}
          github-token: ${{ secrets.GITHUB_TOKEN }}

      - name: Enable Corepack
        run: corepack enable

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version-file: '.nvmrc'
          cache: 'yarn'

      - name: Install dependencies
        run: yarn install --immutable

      - name: Run integration tests
        run: yarn test
        env:
          TWENTY_API_URL: ${{ steps.twenty.outputs.server-url }}
          TWENTY_API_KEY: ${{ steps.twenty.outputs.access-token }}
```

你无需配置任何机密——`spawn-twenty-docker-image` 动作会在运行器中直接启动一个临时的 Twenty 服务器，并输出连接详情。 GitHub 会自动提供 `GITHUB_TOKEN` 机密。

若要固定为特定的 Twenty 版本而不是 `latest`，请在工作流顶部修改 `TWENTY_VERSION` 环境变量。

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

如果你不想使用 `create-twenty-app`，而是自行完成设置，可以分两步进行。

\*\*1. 将 `twenty-sdk` 和 `twenty-client-sdk` 添加为依赖项：

```bash filename="Terminal"
yarn add twenty-sdk twenty-client-sdk
```

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

```json filename="package.json"
{
  "scripts": {
    "twenty": "twenty"
  }
}
```

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

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

## 故障排除

如果遇到问题：

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

仍然遇到问题？ 在 [Twenty 的 Discord](https://discord.com/channels/1130383047699738754/1130386664812982322) 上寻求帮助。
