---
title: 本地设置
description: 本指南适用于希望在本地运行 Twenty 的贡献者或好奇的开发人员。
---

## 先决条件

<Tabs>
  <Tab title="Linux 和 MacOS">
    在安装和使用 Twenty 之前，请确保在您的计算机上安装以下内容：

    * [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
    * [Node v24.5.0](https://nodejs.org/en/download)
    * [yarn v4](https://yarnpkg.com/getting-started/install)
    * [nvm](https://github.com/nvm-sh/nvm/blob/master/README.md)

    <Warning>
      `npm` 无法使用，您应该改用 `yarn`。 Yarn 现在与 Node.js 一起提供，因此您不需要单独安装它。
      如果您尚未执行此操作，只需运行 `corepack enable` 即可启用 Yarn。
    </Warning>
  </Tab>

  <Tab title="Windows (WSL)">
    1. 安装 WSL
       以管理员身份打开 PowerShell 并运行：

    ```powershell
    wsl --install
    ```

    现在您应该看到一个提示，要求您重启计算机。 如果没有，请手动重启。

    重启后，一个 powershell 窗口将打开并安装 Ubuntu。 这可能需要一些时间。
    您将看到一个提示，要求为您的 Ubuntu 安装创建用户名和密码。

    2. 安装和配置 git

    ```bash
    sudo apt-get install git

    git config --global user.name "Your Name"

    git config --global user.email "youremail@domain.com"
    ```

    3. 安装 nvm、node.js 和 yarn

    <Warning>
      使用 `nvm` 安装正确的 `node` 版本。 `.nvmrc` 确保所有贡献者使用相同的版本。
    </Warning>

    ```bash
    sudo apt-get install curl

    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
    ```

    关闭并重新打开您的终端以使用 nvm。 然后运行以下命令。

    ```bash

    nvm install # installs recommended node version

    nvm use # use recommended node version

    corepack enable
    ```
  </Tab>
</Tabs>

---

## 步骤 1：Git 克隆

在您的终端中，运行以下命令。

<Tabs>
  <Tab title="SSH (推荐)">
    如果您尚未设置 SSH 密钥，您可以在 [这里](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh) 学习如何设置。

    ```bash
    git clone git@github.com:twentyhq/twenty.git
    ```
  </Tab>

  <Tab title="HTTPS">
    ```bash
    git clone https://github.com/twentyhq/twenty.git
    ```
  </Tab>
</Tabs>

## 步骤 2：定位到项目根目录

```bash
cd twenty
```

您应该从项目的根目录运行以下步骤中的所有命令。

## 步骤 3：设置 PostgreSQL 数据库

<Tabs>
  <Tab title="Linux">
    \*\*选项 1（推荐）：\*\*在本地供应您的数据库：
    使用以下链接在 Linux 机器上安装 Postgresql：[Postgresql 安装](https://www.postgresql.org/download/linux/)

    ```bash
      psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;"
    ```

    注意：您可能需要在命令 `psql` 前添加 `sudo -u postgres` 以避免权限错误。

    \*\*选项 2：\*\*如果您已安装 docker：

    ```bash
      make -C packages/twenty-docker postgres-on-docker
    ```
  </Tab>

  <Tab title="Mac OS">
    \*\*选项 1（推荐）：\*\*通过 `brew` 在本地设置数据库：

    ```bash
      brew install postgresql@16
      export PATH="/opt/homebrew/opt/postgresql@16/bin:$PATH"
      brew services start postgresql@16
      psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;"
    ```

    您可以通过执行以下操作来验证 PostgreSQL 服务器是否正在运行：

    ```bash
      brew services list
    ```

    安装器在通过 Homebrew 安装时可能不会默认创建 `postgres` 用户。 相反，它会创建一个与您的 macOS 用户名（例如，“john”）匹配的 PostgreSQL 角色。
    按照以下步骤检查并在必要时创建 `postgres` 用户：

    ```bash
      # Connect to PostgreSQL
      psql postgres
      or
      psql -U $(whoami) -d postgres
    ```

    在 psql 提示符（postgres=#）下，运行：

    ```bash
     # List existing PostgreSQL roles
     \du
    ```

    您将看到类似于以下的输出：

    ```bash
     Role name | Attributes  | Member of
     -----------+-------------+-----------
     john      | Superuser   | {}
    ```

    如果您没有看到 `postgres` 角色列出，请继续下一步。
    手动创建 `postgres` 角色：

    ```bash
     CREATE ROLE postgres WITH SUPERUSER LOGIN;
    ```

    这将创建一个具备登录权限名为 `postgres` 的超级用户角色。

    ```bash
    角色名 | 属性  | 成员
    -----------+-------------+-----------
    postgres  | 超级用户   | {}
    john      | 超级用户   | {}
    ```

    \*\*选项 2：\*\*如果您已安装 docker：

    ```bash
      make -C packages/twenty-docker postgres-on-docker
    ```
  </Tab>

  <Tab title="Windows (WSL)">
    以下所有步骤应在 WSL 终端（在您的虚拟机内）中运行

    \*\*选项 1：\*\*在本地提供您的 Postgresql：
    使用以下链接在 Linux 虚拟机上安装 Postgresql：[Postgresql 安装](https://www.postgresql.org/download/linux/)

    ```bash
      psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;"
    ```

    注意：您可能需要在命令 `psql` 前添加 `sudo -u postgres` 以避免权限错误。

    \*\*选项 2：\*\*如果您已安装 docker：
    在 WSL 上运行 Docker 增加了额外的复杂性。
    仅在您对涉及的额外步骤感到舒适时使用此选项，包括开启 [Docker Desktop WSL2](https://docs.docker.com/desktop/wsl)。

    ```bash
      make -C packages/twenty-docker postgres-on-docker
    ```
  </Tab>
</Tabs>

您现在可以在 [localhost:5432](localhost:5432) 访问数据库，用户名 `postgres`，密码 `postgres`。

## 步骤 4：设置 Redis 数据库（缓存）

Twenty 需要 Redis 缓存来提供最佳性能

<Tabs>
  <Tab title="Linux">
    \*\*选项 1：\*\*在本地供应您的 Redis：
    使用以下链接在 Linux 机器上安装 Redis：[Redis 安装](https://redis.io/docs/latest/operate/oss_and_stack/install/install-redis/install-redis-on-linux/)

    \*\*选项 2：\*\*如果您已安装 docker：

    ```bash
      make -C packages/twenty-docker redis-on-docker
    ```
  </Tab>

  <Tab title="Mac OS">
    \*\*选项 1（推荐）：\*\*通过 `brew` 在本地设置 Redis：

    ```bash
    brew install redis
    ```

    启动您的 redis server：
    `brew services start redis`

    \*\*选项 2：\*\*如果您已安装 docker：

    ```bash
      make -C packages/twenty-docker redis-on-docker
    ```
  </Tab>

  <Tab title="Windows (WSL)">
    \*\*选项 1：\*\*在本地供应您的 Redis：
    使用以下链接在 Linux 虚拟机上安装 Redis：[Redis 安装](https://redis.io/docs/latest/operate/oss_and_stack/install/install-redis/install-redis-on-linux/)

    \*\*选项 2：\*\*如果您已安装 docker：

    ```bash
      make -C packages/twenty-docker redis-on-docker
    ```
  </Tab>
</Tabs>

如果您需要客户端 GUI，我们推荐 [redis insight](https://redis.io/insight/)（提供免费版）

## 步骤 5：设置环境变量

使用环境变量或 `.env` 文件配置您的项目。 更多信息请参见 [此处](/l/zh/developers/self-host/capabilities/setup)

复制 `/front` 和 `/server` 目录中的 `.env.example` 文件：

```bash
cp ./packages/twenty-front/.env.example ./packages/twenty-front/.env
cp ./packages/twenty-server/.env.example ./packages/twenty-server/.env
```

<Info>
  **多工作区模式：** 默认情况下，Twenty 以单工作区模式运行，在此模式下只能创建一个工作区。 要启用多工作区支持（对于测试基于子域的功能很有用），请在服务器的 `.env` 文件中设置 `IS_MULTIWORKSPACE_ENABLED=true`。 详见 [多工作区模式](/l/zh/developers/self-host/capabilities/setup#multi-workspace-mode)。
</Info>

## 步骤 6：安装依赖项

要构建 Twenty 服务器并向你的数据库预置一些数据，请运行以下命令：

```bash
yarn
```

注意 `npm` 或 `pnpm` 将不起作用

## 步骤 7：运行项目

<Tabs>
  <Tab title="Linux">
    根据您的 Linux 发行版，Redis 服务器可能会自动启动。
    如果没有，请查看您的发行版的 [Redis 安装指南](https://redis.io/docs/latest/operate/oss_and_stack/install/install-redis/)。
  </Tab>

  <Tab title="Mac OS">
    Redis 应该已经在运行中。 如果没有，运行：

    ```bash
    brew services start redis
    ```
  </Tab>

  <Tab title="Windows (WSL)">
    根据您的 Linux 发行版，Redis 服务器可能会自动启动。
    如果没有，请查看您的发行版的 [Redis 安装指南](https://redis.io/docs/latest/operate/oss_and_stack/install/install-redis/)。
  </Tab>
</Tabs>

使用以下命令设置您的数据库：

```bash
npx nx database:reset twenty-server
```

启动服务器、工作程序和前端服务：

```bash
npx nx start twenty-server
npx nx worker twenty-server
npx nx start twenty-front
```

或者，您可以一次启动所有服务：

```bash
npx nx start
```

## 步骤 8：使用 Twenty

**前端**

Twenty 的前端将在 [http://localhost:3001](http://localhost:3001) 运行。
您可以使用默认的演示帐号登录：`tim@apple.dev` （密码：`tim@apple.dev`）

**后端**

* Twenty 的服务器将在 [http://localhost:3000](http://localhost:3000) 启动并运行
* 可在 [http://localhost:3000/graphql](http://localhost:3000/graphql) 访问 GraphQL API
* 可通过 [http://localhost:3000/rest](http://localhost:3000/rest) 访问 REST API

## 故障排除

如果您遇到任何问题，请检查[故障排除](/l/zh/developers/self-host/capabilities/troubleshooting)以获取解决方案。
