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

# Mastra 서버 배포

Mastra는 Node.js, Bun 또는 Deno를 지원하는 모든 플랫폼에서 실행할 수 있는 독립형 Node.js 서버로 애플리케이션을 컴파일합니다.

> **팁:** 이 가이드에서는 `mastra build`로 생성된 독립 실행형 서버를 배포하는 방법을 다룹니다. 기존 Express 또는 Hono 애플리케이션에 Mastra를 통합해야 한다면 대신 [서버 어댑터](https://mastra.zisheng.pro/ko/docs/server/server-adapters)를 참조하세요.

## 애플리케이션 구축

프로젝트 루트에서 빌드 명령을 실행합니다.

```bash
mastra build
```

이 명령은 프로덕션 준비가 완료된 서버가 포함된 `.mastra` 디렉터리를 생성합니다. 사용 가능한 모든 플래그는 [`mastra build`](https://mastra.zisheng.pro/ko/reference/cli/mastra) 레퍼런스를 참조하세요.

## 빌드 출력

구축 후 Mastra는 다음 구조를 생성합니다.

```text
.mastra/
├── .build/                # Intermediate build artifacts (module maps, analysis)
└── output/
    ├── index.mjs          # Server entry point
    ├── mastra.mjs         # Your bundled Mastra configuration
    ├── tools.mjs          # Aggregated tool exports
    ├── tools/             # Individual tool bundles
    ├── package.json       # Production dependencies
    ├── node_modules/      # Installed dependencies
    ├── .npmrc             # Copied from your project (if present)
    ├── public/            # Static assets (if src/mastra/public exists)
    └── playground/        # Studio UI (if --studio flag used)
```

`output` 디렉터리는 독립적으로 실행할 수 있습니다. 어느 서버에든 복사해 직접 실행할 수 있습니다.

## 서버 실행

Mastra CLI를 사용하여 서버를 시작합니다.

```bash
mastra start
```

또는 Node.js로 직접 실행하세요.

```bash
node .mastra/output/index.mjs
```

그만큼`mastra start` command provides additional features:

- `.env.production`과 `.env`에서 환경 변수를 로드합니다.
- 누락된 모듈에 대해 유용한 오류 메시지를 제공합니다.
- 정상적인 종료를 위해 프로세스 신호를 처리합니다. 사용 가능한 모든 플래그는 [`mastra start`](https://mastra.zisheng.pro/ko/reference/cli/mastra) 레퍼런스를 참조하세요.

## 빌드 구성

### 빌드 시간 구성

Mastra는 애플리케이션을 빌드할 때 `bundler`, `deployer`, `server` 옵션을 읽습니다. 빌드가 해당 옵션을 추출할 수 있도록 `new Mastra()`에 전달하는 객체의 직접 속성으로 유지하세요. 다음 항목 파일 형태가 작동합니다.

```typescript
import { Mastra } from '@mastra/core/mastra'

export const mastra = new Mastra({
  bundler: {
    externals: ['sharp'],
  },
  server: {
    port: 4111,
  },
})
```

각 옵션의 값은 변수, 가져오기 또는 함수 호출에서 나올 수 있습니다. 옵션 자체는 직접 속성으로 유지되어야 합니다. 팩토리 호출이나 객체 확산 뒤에 빌드 타임 옵션을 숨기지 마세요.

```typescript
const options = {
  bundler: {
    externals: ['sharp'],
  },
}

// These patterns prevent Mastra from extracting `bundler` during the build.
export const mastra = new Mastra(createMastraOptions())
export const otherMastra = new Mastra({ ...options })
```

Mastra가 옵션을 추출할 수 없으면 해당 옵션에 기본 빌드 동작을 사용합니다. 사용 가능한 `bundler`, `deployer`, `server` 설정은 [구성 레퍼런스](https://mastra.zisheng.pro/ko/reference/configuration)를 참조하세요.

### 공용 폴더

Mastra 디렉터리(`src/mastra/public`)에 `public` 폴더가 있으면 빌드 중 해당 내용이 출력 디렉터리로 복사됩니다. 서버는 이 파일들을 정적 에셋으로 제공합니다.

### 마스트라 구성

빌드 프로세스는 Mastra 인스턴스의 구성을 따릅니다. CORS, 시간 초과, 미들웨어 같은 서버 동작은 [서버 개요](https://mastra.zisheng.pro/ko/docs/server/mastra-server)를 참조하세요. 사용 가능한 모든 옵션은 [구성 레퍼런스](https://mastra.zisheng.pro/ko/reference/configuration)를 참조하세요.

## 빌드 프로세스

빌드는 다음 단계를 따릅니다.

1. **진입점 파일 찾기**: Mastra 디렉터리에서 `index.ts` 또는 `index.js`를 찾습니다.
2. **Tool 검색**: 테스트 파일을 제외하고 `{mastraDir}/tools/**/*.{js,ts}`와 일치하는 Tool 파일을 검색합니다.
3. **종속성 분석**: 번들에 포함할 패키지와 외부에 설치할 패키지를 결정합니다.
4. **코드 번들링**: 트리 셰이킹과 선택적 소스 맵을 적용해 Rollup으로 번들링합니다.
5. **서버 생성**: Hono 기반 HTTP 서버를 `index.mjs`로 생성합니다.
6. **종속성 설치**: 출력 디렉터리에서 `npm install`을 실행합니다.
7. **에셋 복사**: `public` 폴더와 `.npmrc`가 있으면 복사합니다.

## 환경변수

| 변수                   | 설명                                                     |
| -------------------- | ------------------------------------------------------ |
| `PORT`               | 서버 포트(기본값: `4111`)                                     |
| `MASTRA_STUDIO_PATH` | Studio 빌드 디렉터리 경로(기본값: `./playground`)                 |
| `MASTRA_SKIP_DOTENV` | 설정된 경우 `.env` 파일 로드를 건너뜀                               |
| `NODE_OPTIONS`       | Node.js 옵션(예: 빌드 메모리 문제에는 `--max-old-space-size=4096`) |

## 서버 엔드포인트

구축된 서버는 상태 확인, Agent, Workflow 등에 대한 엔드포인트를 노출합니다.

| 엔드포인트                                                                                                        | 설명                                              |
| ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- |
| `GET /health`                                                                                                | 상태 확인 엔드포인트이며 `200 OK` 반환                       |
| `GET /api/openapi.json`                                                                                      | OpenAPI 명세(`server.build.openAPIDocs`가 활성화된 경우) |
| `GET /swagger-ui`                                                                                            | 대화형 API 문서(`server.build.swaggerUI`가 활성화된 경우)   |
| 이 목록은 전체 목록이 아닙니다. 모든 엔드포인트를 보려면 `mastra dev`를 실행하고 `http://localhost:4111/swagger-ui`를 방문하세요.               |                                                 |
| 고유한 엔드포인트를 추가하려면 다음을 참조하세요.[Custom API Routes](https://mastra.zisheng.pro/ko/docs/server/custom-api-routes). |                                                 |

## 문제 해결

### 빌드 중 Memory 오류

당신이 만난다면`JavaScript heap out of memory` errors:

```bash
NODE_OPTIONS="--max-old-space-size=4096" mastra build
```

## 관련된

- [서버 개요](https://mastra.zisheng.pro/ko/docs/server/mastra-server): 서버 동작, 미들웨어, 인증 구성
- [서버 어댑터](https://mastra.zisheng.pro/ko/docs/server/server-adapters): 대신 Express나 Hono를 사용하세요.`mastra build`
- [사용자 정의 API 경로](https://mastra.zisheng.pro/ko/docs/server/custom-api-routes): 사용자 정의 HTTP 엔드포인트 추가
- [구성 참조](https://mastra.zisheng.pro/ko/reference/configuration): 전체 구성 옵션