> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/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
```

## 建立模式

### 預設起始專案

預設起始專案會建立包含 Workspace Tool、記憶體、任務追蹤、網路存取、週期性排程、儲存空間與可觀測性的 Agent harness。選擇 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
```