---
title: "보안 강화와 함께 Look Scanned How-To 문서를 VitePress로 마이그레이션"
description: "Look Scanned가 Vue + Vite에서 VitePress로 마이그레이션하여 문서 인프라를 업그레이드하는 동시에 OIDC를 사용한 npm Trusted Publishers를 구현하여 토큰 없는 안전한 패키지 릴리스를 실현한 방법을 알아보세요."
date: 2025-12-19T07:55:33.000Z
lang: ko
source: https://lookscanned.io/ko/blog/migrating-look-scanned-how-to-to-vitepress
tags: ["vitepress", "문서", "보안", "cicd", "npm"]
---

# 보안 강화와 함께 Look Scanned How-To 문서를 VitePress로 마이그레이션

[Look Scanned](https://lookscanned.io)에서는 더 나은 문서와 더 안전한 개발 관행을 제공하기 위해 인프라를 지속적으로 개선하고 있습니다. 오늘은 How-To 문서 사이트의 중요한 업그레이드에 대한 세부 정보를 공유하게 되어 기쁩니다. 커스텀 Vue + Vite 애플리케이션에서 VitePress로 마이그레이션하는 동시에 npm Trusted Publishers를 사용하여 CI/CD 보안을 강화했습니다.

## 📚 VitePress로 마이그레이션한 이유

우리의 How-To 문서 사이트([github.com/lookscanned/how-to](https://github.com/lookscanned/how-to))는 Look Scanned의 포괄적인 사용 가이드 역할을 합니다. 이전 Vue + Vite 설정이 잘 작동했지만, 콘텐츠 중심 문서 사이트에는 VitePress가 더 적합하다는 것을 인식했습니다.

### VitePress란 무엇인가요?

VitePress는 문서를 위해 특별히 설계된 정적 사이트 생성기입니다. Vite와 Vue 3 위에 구축되어 두 가지의 장점을 결합합니다. 즉시 사용 가능한 강력한 문서 기능과 함께 매우 빠른 개발 경험을 제공합니다.

### 마이그레이션의 주요 이점

**🎯 문서를 위한 더 나은 아키텍처**
- **파일 기반 라우팅**: 각 markdown 파일이 자동으로 페이지가 되어 콘텐츠 구성이 직관적입니다
- **내장 문서 기능**: 목차, 검색, 국제화 등이 사전 구성되어 있습니다
- **정적 사이트 생성**: 사전 렌더링된 HTML은 우수한 SEO와 즉각적인 페이지 로드를 제공합니다

**⚡ 개선된 개발자 경험**
- **즉각적인 핫 리로드**: 개발 중 변경 사항이 즉시 나타납니다
- **Markdown 우선**: 컴포넌트 스캐폴딩이 아닌 콘텐츠에 집중
- **Vue 컴포넌트 지원**: 필요할 때 markdown 내에서 커스텀 Vue 컴포넌트를 사용할 수 있습니다

**🔧 더 쉬운 유지 관리**
- **더 명확한 구조**: 문서가 규칙을 따르므로 기여자의 인지 부하가 감소합니다
- **더 안정적인 빌드**: VitePress의 독단적인 구조는 더 재현 가능한 빌드로 이어집니다
- **더 나은 협업**: 팀원은 깊은 Vue 지식 없이도 문서에 기여할 수 있습니다

## 🔒 npm Trusted Publishers로 보안 강화

VitePress 마이그레이션과 함께 중요한 보안 개선 사항을 구현했습니다. **OIDC 인증을 사용한 npm Trusted Publishers**입니다.

### 기존 npm 토큰의 문제점

이전에는 npm에 패키지를 게시하려면 리포지토리 시크릿에 장기 `NPM_TOKEN`을 저장해야 했습니다. 이 접근 방식에는 몇 가지 단점이 있습니다.

- **보안 위험**: 토큰이 실수로 노출되거나 손상될 수 있습니다
- **관리 오버헤드**: 토큰은 수동 회전 및 업데이트가 필요합니다
- **감사 문제**: 누가 무엇을 언제 게시했는지 추적하기 어렵습니다

### 솔루션: OIDC 기반 신뢰할 수 있는 게시

[npm Trusted Publishers](https://docs.npmjs.com/trusted-publishers/)는 OpenID Connect(OIDC)를 활용하여 GitHub Actions에서 직접 안전하고 토큰 없는 게시를 가능하게 합니다. 작동 방식은 다음과 같습니다.

1. **저장된 시크릿 없음**: 토큰을 저장하는 대신 GitHub Actions가 npm에서 단기 자격 증명을 요청합니다
2. **신원 확인**: npm은 게시 요청이 승인된 GitHub 리포지토리에서 온 것인지 확인합니다
3. **자동 자격 증명 관리**: 자격 증명이 자동으로 발급되고 빠르게 만료됩니다

### 실제 이점

이 변경으로 개발 워크플로에 즉각적인 개선이 이루어집니다.

- ✅ **더 이상 토큰 관리 불필요**: npm 토큰을 생성, 저장 또는 회전할 필요가 없습니다
- ✅ **공격 표면 감소**: 단기 자격 증명으로 노출 위험을 최소화합니다
- ✅ **더 나은 감사 가능성**: 모든 게시 작업이 특정 GitHub Actions 실행에 연결됩니다
- ✅ **현대적인 모범 사례**: 제로 트러스트 보안 원칙과 일치합니다

**기술적 참고 사항**: npm Trusted Publishers를 지원하기 위해 CI 구성을 Node.js `lts/*`를 사용하도록 업데이트하여 OIDC 인증에 필요한 최신 npm 버전을 확보했습니다.

## 📦 릴리스 타임라인

마이그레이션은 2025년 12월 19일에 세 가지 릴리스를 통해 완료되었습니다.

- **v2.0.0**: Vue + Vite에서 VitePress로의 핵심 마이그레이션(주요 변경 사항)
- **v2.0.1**: 적절한 Node.js 버전으로 npm Trusted Publishers를 지원하기 위한 CI 수정
- **v2.0.2**: `@fontsource/noto-mono`를 devDependencies로 이동하여 성능 개선

## 🌍 지속적인 다국어 지원

중요한 참고 사항: How-To 문서는 메인 Look Scanned 애플리케이션([lookscanned.io/en/scan](https://lookscanned.io/en/scan)에서 사용 가능)에서 항상 예제 파일로 사용되어 온 다국어 PDF를 생성합니다. 이 VitePress 마이그레이션은 해당 기능을 변경하지 않으며, 단순히 문서 인프라를 유지 및 개선하기 위한 더 나은 기반을 제공합니다.

## 💡 사용자에게 의미하는 바

Look Scanned의 문서를 사용하는 경우:

- **동일한 액세스, 더 나은 경험**: 문서는 동일한 URL에 유지되며 로딩 및 탐색이 개선됩니다
- **더 안정적**: 정적 사이트 생성은 더 빠른 로딩과 더 나은 안정성을 의미합니다
- **더 나은 검색 및 발견**: VitePress의 내장 검색으로 답을 더 빠르게 찾을 수 있습니다
- **지속적인 PDF 지원**: 다국어 PDF 생성이 이전처럼 계속됩니다

## 🚀 다음은 무엇인가

인프라 업그레이드가 완료되면서 콘텐츠 개선에 집중하고 있습니다.

- **확장된 사용 사례**: 더 많은 실용적인 예제와 단계별 가이드
- **일관성 개선**: 명확성을 위해 다국어 용어 개선
- **향상된 PDF 내보내기**: 크로스 브라우저 PDF 생성 경험 개선

## 오늘 Look Scanned를 사용해 보세요

Look Scanned는 파일을 어디에도 업로드하지 않고 브라우저 기반의 프라이버시 우선 PDF 스캔 효과를 제공합니다. 개선된 문서로 시작하기가 그 어느 때보다 쉬워졌습니다.

👉 **브라우저에서 빠르고 안전한 문서 스캔을 경험하려면 [lookscanned.io](https://lookscanned.io)를 방문하세요.**