> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/llms.txt

# create-mastra

建立獨立的 Mastra 項目。`create-mastra` 預設會安裝起始項目，並為你選擇的模型 Provider 完成設定。

**npm**:

```bash
npx create-mastra@latest
```

**pnpm**:

```bash
pnpm dlx create-mastra@latest
```

**Yarn**:

```bash
yarn dlx create-mastra@latest
```

**Bun**:

```bash
bun x create-mastra@latest
```

## 建立模式

### 預設起始項目

預設起始項目會建立 Agent harness，當中包含 Workspace Tool、記憶、任務追蹤、網絡存取、週期排程、儲存及可觀測性功能。你可以選擇 OpenAI、Anthropic、Gemini 或 xAI 作為模型 Provider。

同時提供項目名稱及 Provider，即可毋須回應提示而建立項目。以下範例使用 Anthropic；你亦可傳入 `openai`、`google` 或 `xai`：

**npm**:

```bash
npx create-mastra@latest my-mastra-project --llm anthropic
```

**pnpm**:

```bash
pnpm dlx create-mastra@latest my-mastra-project --llm anthropic
```

**Yarn**:

```bash
yarn dlx create-mastra@latest my-mastra-project --llm anthropic
```

**Bun**:

```bash
bun x create-mastra@latest my-mastra-project --llm anthropic
```

省略 `--llm`，即可透過互動方式選擇 Provider，並可選擇輸入其 API 金鑰。互動設定亦會詢問是否將項目連接至 Mastra 平台。啟用後，指令會在瀏覽器開啟驗證流程，並建立與本機項目同名的平台項目，然後將 `MASTRA_PLATFORM_ACCESS_TOKEN` 及 `MASTRA_PROJECT_ID` 寫入 `.env`。

### 範本

使用範本 slug 或公開 GitHub URL：

**npm**:

```bash
npx create-mastra@latest my-mastra-project --template agent-harness
```

**pnpm**:

```bash
pnpm dlx create-mastra@latest my-mastra-project --template agent-harness
```

**Yarn**:

```bash
yarn dlx create-mastra@latest my-mastra-project --template agent-harness
```

**Bun**:

```bash
bun x create-mastra@latest my-mastra-project --template agent-harness
```

**npm**:

```bash
npx create-mastra@latest my-mastra-project --template https://github.com/mastra-ai/template-agent-harness
```

**pnpm**:

```bash
pnpm dlx create-mastra@latest my-mastra-project --template https://github.com/mastra-ai/template-agent-harness
```

**Yarn**:

```bash
yarn dlx create-mastra@latest my-mastra-project --template https://github.com/mastra-ai/template-agent-harness
```

**Bun**:

```bash
bun x create-mastra@latest my-mastra-project --template https://github.com/mastra-ai/template-agent-harness
```

將範本值留空，以互動方式選擇範本：

**npm**:

```bash
npx create-mastra@latest my-mastra-project --template
```

**pnpm**:

```bash
pnpm dlx create-mastra@latest my-mastra-project --template
```

**Yarn**:

```bash
yarn dlx create-mastra@latest my-mastra-project --template
```

**Bun**:

```bash
bun x create-mastra@latest my-mastra-project --template
```

範本作者自行管理其依賴套件、模型、環境變數及原始碼。`create-mastra` 不會套用 `--llm` 或 `--llm-api-key`。

### 空白框架

使用 `--empty` 建立不含 Provider、Agent、範例、模型 SDK 或環境檔案的項目：

**npm**:

```bash
npx create-mastra@latest my-empty-project --empty
```

**pnpm**:

```bash
pnpm dlx create-mastra@latest my-empty-project --empty
```

**Yarn**:

```bash
yarn dlx create-mastra@latest my-empty-project --empty
```

**Bun**:

```bash
bun x create-mastra@latest my-empty-project --empty
```

## 自動設定

安裝依賴套件後，指令會：

1. 偵測 `PATH` 上支援的編程助手，並安裝 Mastra Skill。如偵測不到任何編程助手，則安裝通用 Skill。
2. 如目前目錄及所產生的項目尚未位於 Git 儲存庫內，則建立初始 Git commit。

使用 `--no-skills` 或 `--no-git` 可略過這些步驟。Skill 或 Git 設定失敗時會顯示警告，但不會移除已成功建立的項目。

## 衝突及驗證

- `--empty` 與 `--template` 不可同時使用。
- `--llm` 與 `--llm-api-key` 只適用於預設起始項目。
- 項目名稱必須是安全、全小寫的單一目錄名稱，而且目標不可已經存在。

系統會在擷取範本或建立檔案前拒絕無效輸入。

## 引數及旗標

**\[project-name]** (`string`): 項目目錄及套件名稱。省略時，指令會提示你輸入。

**--empty** (`boolean`): 建立最精簡且不含 Provider 的 Mastra 項目。

**-l, --llm \<provider>** (`string`): 受管理的 Agent harness Provider：openai、anthropic、google 或 xai。

**-k, --llm-api-key \<key>** (`string`): 自動 Provider 設定成功後，將所選 Provider 的 API 金鑰寫入產生的 .env 檔案。

**--no-skills** (`boolean`): 略過自動安裝 Mastra Skill。

**--no-git** (`boolean`): 略過自動初始化 Git 及初始 commit。

**--no-install** (`boolean`): 略過安裝依賴套件。

**-t, --template \[template]** (`string`): 使用範本 slug 或公開 GitHub URL。省略此值可透過互動方式選擇。

**--timeout \<milliseconds>** (`number`): 安裝依賴套件的逾時時間（正整數）。預設為 60000。

**--version** (`boolean`): 顯示 create-mastra 版本。

**--help** (`boolean`): 顯示指令說明。

## 遙測

Mastra 會收集匿名 CLI 使用資料，例如作業系統、Mastra 版本及 Node.js 版本。你可查看[分析原始碼](https://github.com/mastra-ai/mastra/blob/main/packages/cli/src/analytics/index.ts)。

設定 `MASTRA_TELEMETRY_DISABLED=1` 即可選擇退出：

```bash
MASTRA_TELEMETRY_DISABLED=1 npx create-mastra@latest my-project --empty
```