> ## Documentation Index > Fetch the complete documentation index at: https://docs.twenty.com/llms.txt > Use this file to discover all available pages before exploring further. # 快速开始 > 几分钟内创建你的第一个 Twenty 应用。 ## 先决条件 * **Node.js 24.5+** — [在此下载](https://nodejs.org/) * **Yarn 4** — 通过 Corepack 随 Node.js 提供。启用它：`corepack enable` * **Docker** — [在此下载](https://www.docker.com/products/docker-desktop/)。运行本地 Twenty 服务器所需。如果你已经在其他地方运行了 Twenty，请跳过。构建一个 Twenty 应用包含三个阶段。脚手架工具将它们合并为一个理想路径的命令，但每个阶段都是独立的概念——当出现问题时，知道自己处于哪个阶段可以指明需要修复什么。 | 阶段 | 你要做什么 | 工具 | 结果 | | ------------ | -------------------- | ----------------------------------- | -------------------- | | **1. 脚手架** | 生成应用的源代码 | `npx create-twenty-app` | 磁盘上的一个 TypeScript 项目 | | **2. 运行服务器** | 启动一个 Twenty 服务器以进行同步 | Docker + `yarn twenty docker:start` | 一个正在运行的 Twenty 实例 | | **3. 同步** | 将你的代码实时同步到服务器 | `yarn twenty dev` | 你的更改会出现在 UI 中 | *** ## 阶段 1 — 搭建项目脚手架从模板创建一个新应用： ```bash filename="Terminal" theme={null} npx create-twenty-app@latest my-twenty-app ``` 脚手架是非交互式的：目录名称会成为应用名称。传递 `--display-name` 和 `--description` 来自定义生成的元数据（你也可以稍后在 `src/constants/universal-identifiers.ts` 中进行编辑）。这将在 `my-twenty-app/` 中生成一个 TypeScript 项目，包含一个入门版的 `application-config.ts`、一个默认角色、CI/CD 工作流，以及一个集成测试。 **完成此阶段后：** 你的机器上已有该应用的源代码。它还未运行——那是第 2 阶段的内容。 *** ## 阶段 2 — 运行本地 Twenty 服务器你的应用需要一个 Twenty 服务器来进行同步。该服务器是一个完整的 Twenty 实例——包含 UI、GraphQL API、PostgreSQL——在本地的 Docker 中运行。你的本地代码会将其定义上传到该服务器，从而使其显示在 UI 中。脚手架会为你启动一个：在 Docker 正在运行的情况下，它会拉取 `twentycrm/twenty-app-dev` 镜像，在端口 `2020` 上启动，并将 CLI 认证到预置的演示工作区（`tim@apple.dev`）——无需登录。若要改为连接到现有的 Twenty 服务器，请传入 `--url \`。远程服务器通过 OAuth 进行身份验证：会打开一个浏览器窗口，你可以登录并点击 **Authorize**，从而授予 CLI 访问你工作区的权限。（你也可以在本地选择使用 OAuth，方式是添加 `--authentication-method oauth` —— 使用 `tim@apple.dev` / `tim@apple.dev` 登录。）

你的终端会确认一切已就绪。

**完成此阶段后：** 你在 [http://localhost:2020](http://localhost:2020) 上拥有一个正在运行的 Twenty 服务器，且你的 CLI 已获授权可与其同步。如果未安装或未运行 Docker，脚手架工具会告诉你在所用操作系统上正确的启动命令。 Docker 启动后，你可以通过 `yarn twenty docker:start` 继续——无需重新生成脚手架。 *** ## 阶段 3 — 同步你的更改这是你大部分时间所处的内循环。 ```bash filename="Terminal" theme={null} cd my-twenty-app yarn twenty dev ``` 它会监视 `src/`，在每次更改时重新构建，并将结果同步到服务器。编辑文件、保存，服务器会在几秒内反映出更改。你会在终端中看到一个实时状态面板。如需更详细的输出（构建日志、同步请求、错误跟踪），请添加 `--verbose`。

打开 [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer)。你应当在 **你的应用** 下看到你的应用。

点击 **My twenty app** 查看其**应用注册**——一条用于描述你的应用（名称、标识符、OAuth 凭据、来源）的服务器级记录。同一服务器上的多个工作区可以安装同一个注册项。

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

**完成此阶段后：** 你拥有一个实时的开发循环。编辑 `src/` 中的任意文件，更改会显示在 UI 中。 ### 用于 CI 和脚本的一次性同步使用 `plan` 和 `apply` 在无监视器的情况下各运行一次相同的流水线： ```bash filename="Terminal" theme={null} yarn twenty plan # preview the metadata changes without applying them yarn twenty apply # show the plan, then apply it ``` | 命令 | 行为 | 适用场景 | | ------------------- | ------------------------------------------------------------------ | ------------------------------- | | `yarn twenty dev` | 监视并在每次更改时重新同步。持续运行，直到你将其停止。 | 交互式本地开发。 | | `yarn twenty apply` | 单次构建与同步，成功时以 `0` 退出，失败时以 `1` 退出。在执行破坏性变更前会要求确认（传入 `--force` 可跳过）。 | CI、pre-commit 钩子、AI 智能体、脚本化工作流。 | | `yarn twenty plan` | 构建并打印元数据更改，**但不会应用这些更改**。 | 在提交同步之前检查它会更改哪些内容。 | 所有模式都需要经过身份验证的远程服务器。有关 `plan` 的更多信息，请参见 [同步与恢复](/l/zh/developers/extend/apps/operations/sync-and-recovery#previewing-changes-plan)。 `yarn twenty dev --once` 和 `yarn twenty dev --once --dry-run` 是 `yarn twenty apply` 和 `yarn twenty plan` 的已弃用别名。 ### 开发模式选项 | 标志 | 描述 | | ----------------------- | ------------------------------ | | `--force` | 在不经确认的情况下应用破坏性变更（删除）。 | | `--debounceMs \` | 以毫秒为单位设置文件更改的防抖延迟（默认值：`1000`）。 | | `--verbose` / `--debug` | 显示详细的构建日志、同步请求和错误跟踪。 | ## 你可以构建的内容应用由**实体**组成——每个实体定义为一个包含单一 `export default` 的 TypeScript 文件： | 实体 | 作用 | | ---------- | ------------------------------------------ | | **对象与字段** | 自定义数据模型（明信片、发票等）带有类型化字段 | | **逻辑函数** | 由 HTTP 路由、cron 调度或数据库事件触发的服务端 TypeScript | | **前端组件** | 在 Twenty 的 UI 内渲染的 React 组件（侧边面板、小部件、命令菜单） | | **技能与智能体** | AI 能力——可复用的指令和自主助手 | | **视图与导航** | 预配置的列表视图和侧边栏菜单项 | | **页面布局** | 带有选项卡和小部件的自定义记录详情页 | 完整参考：[概念](/l/zh/developers/extend/apps/getting-started/concepts)。 ## 后续步骤应用标识、默认角色、安装和卸载钩子、公共资源。对象、字段和双向关系。逻辑函数、技能、智能体和 OAuth 连接。视图、导航、页面布局、前端组件。 CLI、测试、远程、CI，以及发布你的应用。