> ## Documentation Index
> Fetch the complete documentation index at: https://docs.logbrew.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Vite로 JavaScript 소스맵 업로드하기

> Vite 빌드의 JavaScript 소스맵을 업로드하세요. 자격 증명은 앱에 넣지 마세요. 압축된 스택 프레임을 원본 소스 위치로 매핑하세요.

압축된 JavaScript 파일에서는 여러 소스 줄이 한 줄에 들어갈 수 있습니다. 이 파일에서 나온 스택 프레임은 생성된 코드의 줄과 열을 가리킵니다. [소스맵](https://ecma-international.org/publications-and-standards/standards/ecma-426/)은 이 위치를 원본 파일, 줄, 열에 연결합니다.

이 가이드는 `@logbrew/sdk` 0.1.28의 Vite 플러그인을 사용합니다. Vite 앱, 앱의 빌드 결과물에 대한 접근 권한, 프로젝트 키를 만들 권한이 필요합니다. Apple 디버그 파일은 [Apple 크래시와 멈춤](/ko/guides/apple-crashes-and-hangs)을 참고하세요.

## 빌드와 이벤트의 정보 맞추기

업로드와 앱의 런타임 이벤트에 같은 프로젝트, 릴리스, 환경, 서비스를 사용하세요. 버전 이름은 [릴리스](/ko/concepts/releases)를 참고하세요. 이 가이드에서는 `web@1.2.3`, `staging`, `checkout-web`을 사용합니다.

빌드된 코드가 바뀌면 릴리스도 바꾸세요. 준비된 빌드를 업로드한 다음, 바로 그 빌드를 배포하세요. 업로드한 뒤에는 다시 빌드하거나 JavaScript를 수정하지 마세요.

## Vite 플러그인 추가하기

앱 디렉터리에 SDK를 설치하세요.

```bash theme={null}
npm install @logbrew/sdk@0.1.28
```

`vite.config.js`에 플러그인을 추가하세요. 다른 플러그인과 빌드 설정은 그대로 두세요. 프로젝트 ID를 바꾸세요.

```js theme={null}
import { createLogBrewViteReleaseArtifactsPlugin } from "@logbrew/sdk/vite-release-artifacts";

export default {
  plugins: [
    createLogBrewViteReleaseArtifactsPlugin({
      projectId: "<project_id>",
      release: "web@1.2.3",
      environment: "staging",
      service: "checkout-web",
      minifiedPathPrefix: "https://app.example.com"
    })
  ]
};
```

`minifiedPathPrefix`는 빌드 디렉터리가 배포된 URL입니다. 플러그인은 이 디렉터리 안의 각 파일 경로를 이 값 뒤에 붙입니다. 예를 들어 `dist/assets/app.js`는 `https://app.example.com/assets/app.js`가 됩니다. 빌드를 `/web`에서 제공한다면 접두사에 `/web`을 포함하세요. 접두사에 `/assets`는 추가하지 마세요.

`upload` 옵션이 없으면 플러그인은 LogBrew로 아무것도 보내지 않습니다. 플러그인은 다음 작업도 합니다.

* `build.sourcemap`을 설정하지 않으면 `"hidden"`으로 설정합니다. `false`로 설정했다면 `"hidden"`으로 바꾸세요.
* 압축 도구 옵션을 설정하지 않으면 함수 이름을 유지합니다. 직접 옵션을 설정했다면 그 옵션에서도 이름을 유지하세요.

숨긴 소스맵은 일반 파일로 빌드 결과물에 남습니다. 접근 제어가 적용되지 않습니다. 인라인 소스맵은 사용하지 마세요. 플러그인은 JavaScript 파일 안에 들어 있는 맵을 받지 않습니다.

## 로컬에서 빌드하고 확인하기

프로덕션 빌드를 실행하세요.

```bash theme={null}
npm run build
```

플러그인은 각 JavaScript 파일과 그 소스맵에 같은 Debug ID를 부여합니다. 포함된 `sourcesContent`와 로컬 앱 루트 경로를 제거합니다. 그리고 `dist/logbrew-release-artifacts.json`을 작성합니다.

매니페스트를 여세요. `validation.status`가 `ready`인지, 이 빌드의 파일과 배포 URL이 나열되어 있는지 확인하세요. 숨긴 맵 때문에 `sourceMappingURL comment missing` 경고가 나옵니다. 이 경고는 정상입니다.

비공개 경로나 공유하고 싶지 않은 소스 텍스트가 들어 있는 맵은 업로드하지 마세요. 업로드에는 컴파일된 JavaScript도 들어가므로 앱 번들에 시크릿을 넣지 마세요.

로컬에서 업로드를 확인하세요. 이 명령어는 요청을 보내지 않으며 키도 필요 없습니다.

```bash theme={null}
npx --no-install logbrew-release-artifacts upload-js \
  --build-dir dist \
  --manifest dist/logbrew-release-artifacts.json \
  --endpoint https://api.logbrew.co/api/release-artifacts \
  --allow-hosted \
  --dry-run
```

명령어가 코드 `0`으로 종료되고 `"status": "dry_run"`을 출력할 때만 계속 진행하세요. 이 명령어는 로컬 파일과 매니페스트를 확인합니다. 서버는 테스트하지 않습니다. 빌드가 다른 출력 디렉터리를 쓴다면 두 경로를 모두 바꾸세요.

매핑을 확인하려면 빌드된 앱을 실행하고, 생성된 스택 프레임 1개를 파일, 줄, 열과 함께 복사하세요.

```bash theme={null}
npx --no-install logbrew-release-artifacts symbolicate-js \
  --build-dir dist \
  --manifest dist/logbrew-release-artifacts.json \
  --stack-frame "at checkoutTotal (https://app.example.com/assets/index-a1b2c3.js:2:780)"
```

결과에 `"status": "resolved"`가 있는지 확인하세요. `original` 객체는 소스 파일, 줄, 열을 보여 줍니다. 이 명령어는 로컬에서 실행되며 아무것도 업로드하지 않습니다.

## <span id="create-an-artifact-key">아티팩트 키 만들기</span>

[LogBrew CLI](/ko/guides/cli)로 로그인하세요. 프로젝트 ID를 찾으세요.

```bash theme={null}
logbrew projects --json
```

프로젝트에 아티팩트 키를 만드세요. 소유자만 접근할 수 있는 디렉터리에 새 파일 경로를 지정하세요.

```bash theme={null}
install -d -m 700 "$HOME/.logbrew" &&
logbrew projects keys create "<project_id>" \
  --ingest-key-file "$HOME/.logbrew/checkout-web.artifact" \
  --label "Checkout web build" \
  --kind artifact \
  --json
```

명령어가 성공한 뒤에만 계속 진행하세요. 결과가 분명하지 않으면 같은 인수로 같은 명령어를 다시 실행하세요. `--abandon-retry`는 사용하지 마세요.

아티팩트 키는 프로젝트 범위의 쓰기 전용 키입니다. 소스맵과 디버그 파일을 업로드합니다. 텔레메트리를 보내거나 아티팩트 메타데이터를 읽을 수는 없습니다. 대신 계정 자격 증명이나 런타임 SDK 키를 쓰지 마세요.

키는 빌드 환경의 시크릿 설정에 `LOGBREW_RELEASE_ARTIFACT_TOKEN`으로 저장하세요. 키를 출력하거나 커밋하지 마세요. `VITE_*`나 `EXPO_PUBLIC_*`처럼 클라이언트에 노출되는 변수에 넣지 마세요.

업로드를 실행하는 프로세스에 이 변수를 설정하세요. 헬퍼는 `.env` 파일을 읽지 않습니다. Vite도 [설정 평가](https://vite.dev/config/#using-environment-variables-in-config) 중에는 이 파일을 `process.env`로 불러오지 않습니다.

## 준비된 빌드 업로드하기

확인을 마친 같은 파일과 매니페스트를 사용하세요. 이 명령어는 업로드를 LogBrew로 보냅니다.

```bash theme={null}
npx --no-install logbrew-release-artifacts upload-js \
  --build-dir dist \
  --manifest dist/logbrew-release-artifacts.json \
  --endpoint https://api.logbrew.co/api/release-artifacts \
  --allow-hosted
```

`"status": "uploaded"`가 나오면 LogBrew가 업로드를 받았다는 뜻입니다. 명령어가 오류와 함께 종료되면 멈추고 아래 표를 참고하세요.

헬퍼는 네트워크 오류, `408`, `429`, `5xx` 응답이 나오면 최대 2번 다시 시도합니다. 매번 같은 준비된 파일을 보냅니다. 횟수를 바꾸려면 `--max-retries`를 사용하세요.

수동 업로드가 잘 되면, 대신 Vite 빌드 중에 업로드할 수도 있습니다. 플러그인 설정에 다음 옵션을 추가하세요.

```js theme={null}
upload: {
  endpoint: "https://api.logbrew.co/api/release-artifacts",
  allowHostedUpload: true,
  tokenEnv: "LOGBREW_RELEASE_ARTIFACT_TOKEN"
}
```

업로드 방식은 하나만 사용하세요. 준비 오류나 업로드 오류가 나면 플러그인이 빌드를 멈춥니다. 업로드 없이 테스트하려면 `dryRun: true`를 추가하세요.

플러그인은 출력 디렉터리에서 소스맵을 삭제하지 않습니다. `.map` 파일이나 매니페스트를 공개 웹사이트나 CDN에 배포하지 마세요.

수집된 이슈의 프레임을 매핑하려면 같은 준비된 빌드를 대상으로 그 프레임과 함께 `symbolicate-js`를 실행하세요.

## <span id="verify-a-new-issue">새 이슈 읽기</span>

같은 준비된 빌드를 테스트 환경에 배포하세요. 이슈 수집 경로로 안전한 테스트 오류 1개를 일으키세요. 이 테스트에서는 사용자 입력, 자격 증명, 원시 스택을 보내지 마세요.

같은 프로젝트와 빌드 컨텍스트로 새 이슈를 찾으세요.

```bash theme={null}
logbrew read issues --project "<project_id>" \
  --release "web@1.2.3" --environment staging \
  --service checkout-web --since 1h --json
```

결과에서 이슈 ID를 복사하세요. 가장 최근 발생 건을 읽으세요.

```bash theme={null}
logbrew investigate issue "<issue_id>" --occurrence latest --json
```

먼저 이벤트 시각, 프로젝트, 서비스, 환경, 릴리스를 확인하세요. 그다음 `event.stack_frames`를 읽으세요. `source: "symbolicated"`인 프레임에는 업로드한 소스맵에서 가져온 원본 파일, 줄, 열이 들어 있습니다. `source: "captured"`인 프레임에는 앱이 보낸 위치가 들어 있습니다.

`logbrew read issue "<issue_id>" --json`도 `symbolication` 객체를 반환합니다. 이 객체의 각 프레임에는 `resolved`, `artifact_not_found`, `source_not_resolved`, `invalid_metadata`, `unavailable` 중 하나인 `status`가 있습니다. `resolved` 프레임에만 원본 위치가 있습니다.

LogBrew는 이슈를 읽을 때 프레임을 매핑합니다. 오류가 난 뒤에 업로드해도 같은 Debug ID를 가진 이전 이벤트를 매핑할 수 있습니다. 매핑된 프레임은 살펴볼 코드를 가리킵니다. 오류의 원인을 보여 주지는 않습니다. 다른 필드는 [이슈 조사하기](/ko/guides/investigate-an-issue)를 참고하세요.

## 확인 실패 시 복구하기

| 결과 | 다음 단계 |
| - | - |
| 매니페스트 상태가 `ready`가 아님 | `validation.errors`를 읽으세요. 빌드 설정을 고치고 다시 빌드하세요. 매니페스트를 직접 수정하지 마세요. |
| 소스맵이 없거나 인라인이라 빌드가 멈춤 | `build.sourcemap`을 `"hidden"`이나 `true`로 설정하세요. 다시 빌드하세요. |
| `auth_missing` | 업로드 프로세스에 `LOGBREW_RELEASE_ARTIFACT_TOKEN`을 설정하세요. 드라이 런으로는 키를 테스트할 수 없습니다. |
| `auth_failed` (`401` 또는 `403`) | 같은 프로젝트의 아티팩트 키를 사용하세요. 런타임 키나 계정 키를 쓰지 마세요. |
| `validation_failed` (`400` 또는 `413`) | 준비된 파일과 그 크기를 확인하세요. 같은 업로드를 다시 보내지 마세요. |
| 로컬 오류가 있는 `validation_failed` | `validation.errors`를 읽으세요. 빌드 후 파일이 바뀌었다면 다시 빌드하고 확인하세요. |
| `retryable_error` | 네트워크 오류, `408`, `429`, 서버 오류 후 재시도가 모두 실패했습니다. 나중에 같은 준비된 파일로 다시 시도하세요. |
| `upload_failed` | 서버가 다른 상태를 반환했습니다. `--endpoint` 값을 확인하세요. |
| 프레임이 매핑되지 않음 | Debug ID, 배포 URL 접두사, 빌드를 확인하세요. 다른 빌드나 릴리스의 맵을 사용하지 마세요. |
| 새 이슈가 나타나지 않음 | 소스맵을 테스트하기 전에 이슈 수집, 런타임 키, 시간 필터를 확인하세요. |

지원 메시지에는 소스 파일, 키, 비공개 경로를 넣지 마세요. [문제 해결](/ko/guides/troubleshooting)과 [API 오류](/ko/reference/api-errors)를 참고하세요.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.