--- title: 开始使用 description: 几分钟内创建你的第一个 Twenty 应用。 --- 应用目前处于 Alpha 阶段。 该功能可用，但仍在演进中。 应用可通过自定义对象、字段、逻辑函数、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` 的新文件夹，其中包含你所需的一切。 脚手架工具支持以下标志： * `--minimal` — 仅创建必要文件，不包含示例（默认） * `--exhaustive` — 创建所有示例实体 * `--name ` — 设置应用名称（跳过提示） * `--display-name ` — 设置显示名称（跳过提示） * `--description ` — 设置描述（跳过提示） * `--skip-local-instance` — 跳过本地服务器设置提示 ## 步骤 2：设置本地 Twenty 实例 脚手架工具会询问： > **是否要设置本地 Twenty 实例？** * **输入 `yes`**（推荐）— 这将拉取 `twenty-app-dev` Docker 镜像，并在端口 `2020` 上启动本地 Twenty 服务器。 继续之前，请确保 Docker 正在运行。 * **输入 `no`** — 如果你已经有一个在本地运行的 Twenty 服务器，请选择此项。
是否启动本地实例？
## 步骤 3：登录你的工作区 接下来，将打开一个浏览器窗口，显示 Twenty 登录页面。 使用预置的演示账户登录： * **邮箱：** `tim@apple.dev` * **密码：** `tim@apple.dev`
Twenty 登录界面
## 步骤 4：授权该应用 登录后，你会看到一个授权界面。 这使你的应用可以与工作区交互。 点击 **授权** 继续。
Twenty CLI 授权界面
授权后，你的终端会确认一切已就绪。
应用脚手架创建成功
## 步骤 5：开始开发 进入你的新应用文件夹并启动开发服务器： ```bash filename="Terminal" cd my-twenty-app yarn twenty dev ``` 它会监听你的源文件，每次更改都会重建，并自动将你的应用同步到本地 Twenty 服务器。 你应当在终端中看到一个实时状态面板。 如需更详细的输出（构建日志、同步请求、错误跟踪），请使用 `--verbose` 标志： ```bash filename="Terminal" yarn twenty dev --verbose ``` 开发模式仅适用于以开发模式运行的 Twenty 实例（`NODE_ENV=development`）。 生产实例会拒绝开发同步请求。 使用 `yarn twenty deploy` 部署到生产服务器——详见[发布应用](/l/zh/developers/extend/apps/publishing)。
开发模式终端输出
## 步骤 6：在 Twenty 中查看你的应用 在浏览器中打开 [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer)。 前往 **设置 > 应用**，并选择 **开发者** 选项卡。 你应当在 **你的应用** 下看到你的应用：
“你的应用”列表显示 My twenty app
点击 **My twenty app** 打开其 **应用注册**。 注册项是一个服务器级记录，用于描述你的应用——其名称、唯一标识符、OAuth 凭据以及来源（本地、npm 或 tarball）。 它位于服务器上，而不在任何特定工作区内。 当你将应用安装到工作区时，Twenty 会创建一个工作区范围的 **应用**，指向该注册项。 同一服务器上的多个工作区可以安装同一个注册项。
应用注册详情
点击 **查看已安装的应用** 以查看已安装的应用。 **关于** 选项卡显示当前版本和管理选项：
已安装的应用 — “关于”选项卡
切换到 **内容** 选项卡，以查看你的应用提供的全部内容——对象、字段、逻辑函数和智能体：
已安装的应用 — “内容”选项卡
一切就绪！ 编辑 `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 ``` 你的凭据存储在 `~/.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` 会创建一个全新实例。 服务器需要 Docker 处于运行状态。 如果看到 "Docker not running" 错误，请确保 Docker Desktop（或 Docker 守护进程）已启动。 ### 命令参考 | 命令 | 描述 | | -------------------------------------- | --------------- | | `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` 以及所有其他命令。 不要全局安装 `twenty-sdk`。 始终将其作为本地项目依赖使用，以便每个项目都能固定其自己的版本。 ## 故障排除 如果遇到问题： * 在使用本地实例启动脚手架工具之前，请确保**Docker 已在运行**。 * 请确保使用 **Node.js 24+**（运行 `node -v` 进行检查）。 * 请确保**已启用 Corepack**（`corepack enable`），以便可使用 Yarn 4。 * 如果依赖似乎有问题，尝试删除 `node_modules` 并重新运行 `yarn install`。 仍然遇到问题？ 在 [Twenty 的 Discord](https://discord.com/channels/1130383047699738754/1130386664812982322) 上寻求帮助。