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

# 모노레포에 배포

모노레포에 Mastra를 배포하는 과정은 독립 실행형 애플리케이션과 동일합니다. 이 가이드에서는 모노레포 관련 고려 사항을 다룹니다. 핵심 빌드 및 배포 단계는 [Mastra 서버 배포](https://mastra.zisheng.pro/ko/docs/deployment/mastra-server)를 참조하세요.

## 지원되는 단일 저장소

Mastra는 다음과 함께 작동합니다.

- npm 작업공간
- pnpm 작업공간
- 원사 작업 공간
- 터보레포

알려진 제한사항:

- Bun Workspace - 부분 지원, 알려진 문제 있음
- Nx - Nx의 [지원되는 종속성 전략](https://nx.dev/concepts/decisions/dependency-management)을 사용할 수 있지만 Workspace 패키지 내부에 `package.json` 파일이 있어야 함

## 예시 구조

이 예에서 Mastra 애플리케이션은 다음 위치에 있습니다.`apps/api`:

```text
apps/
├── api/
│   ├── src/
│   │   └── mastra/
│   │       ├── agents/
│   │       ├── tools/
│   │       ├── workflows/
│   │       └── index.ts
│   ├── package.json
│   └── tsconfig.json
└── web/
packages/
├── ui/
└── utils/
package.json
```

## 모노레포에서 빌드하기

monorepo Tool을 사용하여 올바른 패키지에서 빌드 명령을 실행하세요. 특별한 플래그가 필요하지 않습니다.

예:

**npm**:

```bash
npm run build --workspace=apps/api
```

**pnpm**:

```bash
pnpm --filter api run build
```

**yarn**:

```bash
yarn workspace api build
```

**Turborepo**:

```bash
turbo run build --filter=api
```

패키지의 `build` 스크립트는 `mastra build`를 실행해야 합니다.

```json
{
  "scripts": {
    "build": "mastra build"
  }
}
```

## 작업 공간 패키지

Mastra 애플리케이션이 다른 작업 공간 패키지에서 가져올 때 Mastra는 이를 자동으로 처리합니다.

- 패키지가 미리 컴파일된 경우(예: `tsc` 또는 `tsdown`) Mastra는 컴파일된 JavaScript를 가져옵니다.
- 패키지에 컴파일되지 않은 TypeScript가 포함되어 있으면 Mastra는 빌드 중에 이를 트랜스파일합니다. 대부분의 설정에서는 구성 없이도 작동합니다. 작업공간 패키지 가져오기에 문제가 발생하는 경우 해당 패키지를 다음에 추가하세요.[`transpilePackages`](https://mastra.zisheng.pro/ko/reference/configuration):

```typescript
export const mastra = new Mastra({
  bundler: {
    transpilePackages: ['@my-org/utils'],
  },
})
```

`new Mastra()`에 전달하는 객체의 직접 속성으로 `bundler`를 유지하세요. 지원되는 진입점 파일 형태는 [빌드 시간 구성](https://mastra.zisheng.pro/ko/docs/deployment/mastra-server)을 참조하세요.

## 환경변수

`.env` 파일은 모노레포 루트가 아닌 Mastra 애플리케이션 디렉터리(예: `apps/api/.env`)에 저장하세요.

## 배포 구성

클라우드 Provider에 배포할 때 배포 대상으로 올바른 패키지를 선택했는지 확인하세요. 애플리케이션 디렉터리(예: `apps/api`) 대신 모노레포 루트를 선택하는 것은 흔한 실수입니다. 대부분의 공급자는 대시보드 또는 구성 파일에서 루트 디렉터리를 지정할 수 있습니다.

## 종속성 관리

버전 충돌 및 빌드 오류를 방지하려면 종속성을 일관되게 유지하세요.

- 모든 패키지가 동일한 버전을 확인하도록 모노레포 루트에서 **single lockfile** 사용
- 중복을 방지하도록 Mastra 또는 프레임워크 같은 **shared libraries**의 버전 정렬

## 문제 해결

### Workspace 패키지를 찾을 수 없습니다.

Mastra가 작업 공간 패키지를 확인할 수 없는 경우 다음을 확인하세요.

- 패키지가 `package.json`의 종속성에 나열되어 있는지 확인합니다.
- 잠금 파일이 최신 상태인지 확인합니다(`pnpm install`, `npm install` 등).
- 패키지의 `package.json`에 유효한 `main` 또는 `exports` 필드가 있는지 확인합니다.

### 작업 공간 패키지의 TypeScript 오류

컴파일되지 않은 작업 영역 패키지에서 유형 오류가 표시되면 다음 중 하나를 수행하세요.

- 패키지를 먼저 빌드하세요(더 빠른 Mastra 빌드를 위해 권장).
- Mastra 구성의 [`transpilePackages`](https://mastra.zisheng.pro/ko/reference/configuration)에 패키지를 추가하세요.

## 관련된

- [Mastra 서버 배포](https://mastra.zisheng.pro/ko/docs/deployment/mastra-server): 핵심 빌드 및 배포 가이드
- [구성 레퍼런스](https://mastra.zisheng.pro/ko/reference/configuration): `bundler.transpilePackages` 및 기타 옵션
- [CLI 레퍼런스](https://mastra.zisheng.pro/ko/reference/cli/mastra): 빌드 명령 플래그