wechat-article-exporter — 브라우저에서
돌아가는 콘텐츠 일괄 다운로더

먼저, "위챗 공중호"가 뭐고 왜 백업이 필요한가

왜 이런 도구가 중국 개발자 커뮤니티를 점령했나.

위챗(WeChat·微信)에는 한국의 네이버 블로그 + 카카오 채널과 비슷한 "공중호(公众号)"가 있다. 중국에서 가장 큰 콘텐츠 플랫폼 중 하나다. 하지만 위챗은 모든 글이 위챗 앱 안에 갇혀 있어서, 밖에서 검색하거나 백업하기가 거의 불가능하다. 이 레포는 그 벽을 우회해 글을 통째로 내려받게 해주는 도구다.

2024~2026년 사이 중국에서 공식계정 콘텐츠의 법적 보존, 아카이빙, 마이그레이션 수요가 폭증했다. 정부 규제 변경·플랫폼 삭제 사고가 잦아지면서 "내가 쓴 글을 내 손으로 보관"하려는 흐름이 일반화됐다. 이 레포는 그 정확한 timing을 잡았다.

이 프로젝트의 핵심 메시지

한 문장으로 줄이면.

8.1k 별, 1.4k 포크의 비결

트렌딩 이유 + 경쟁 우위.

트렌딩 이유 — 정확한 timing + 100% 원본 재현

중국 개발자 커뮤니티에서 폭발적으로 입소문이 났다. 위챗 백업 수요(법적 보존, 콘텐츠 아카이빙, 플랫폼 이전)가 워낙 커서 빠르게 확산. 무엇보다 HTML 스타일 재현률 100% — 이미지·CSS·외부 자원까지 함께 묶어 오프라인에서도 완벽히 원본 그대로 보이게 만든다. 단순 텍스트 추출과는 다른 차원이다.

두 번째 강점은 "브라우저에서 직접 돈다"는 점. 일반 크롤러는 서버에서 돌아가서 운영자가 모든 사용자 쿠키를 보관해야 하고, 한 IP에서 들어오는 요청이라 위챗이 쉽게 차단한다. 이 레포는 그 모든 윤리·기술 리스크를 우회한다.

경쟁 비교 — 일반 크롤러 vs 이 레포

전체 기술 지도

프론트엔드 · 백엔드 · 라이브러리 · 인프라.

프론트엔드 — Nuxt 3 SPA

백엔드 — Nitro 서버 엔진

데이터 처리 라이브러리

클라이언트 측 저장소

인프라 · 배포

개발 환경 — 모던 툴체인

시스템 구조와 4가지 핵심 패턴

전체 구조도 → 데이터 흐름 → 설계 패턴.

전체 시스템 구조도

┌─────────────────────────────────────────────────────────────┐
│                    사용자 브라우저 (Chrome 등)                │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Nuxt 3 SPA (app.vue → pages/dashboard.vue)          │   │
│  │  · Vue 3 Composition API (composables/)              │   │
│  │  · AG Grid로 글 목록 표시                              │   │
│  │  · Tailwind + @nuxt/ui로 UI 구성                      │   │
│  └──────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  IndexedDB (Dexie 래퍼) — store/v2/db.ts             │   │
│  │  ├─ article    (글 메타데이터)                         │   │
│  │  ├─ asset      (에셋)                                 │   │
│  │  ├─ comment    (댓글)                                 │   │
│  │  ├─ comment_reply (댓글 답글)                         │   │
│  │  ├─ debug      (디버그)                               │   │
│  │  ├─ html       (원본 HTML)                            │   │
│  │  ├─ info       (계정 정보)                            │   │
│  │  ├─ metadata   (메타데이터)                           │   │
│  │  ├─ resource   (이미지·CSS 캐시)                      │   │
│  │  └─ resource-map (리소스 맵)                          │   │
│  └──────────────────────────────────────────────────────┘   │
└────────────┬────────────────────────────┬───────────────────┘
             │                            │
             │ ① 정적 자원 요청            │ ② 위챗 API 프록시 요청
             ▼                            ▼
┌─────────────────────────────┐  ┌─────────────────────────────┐
│  Cloudflare Pages /         │  │  Nitro 서버 (Edge or Node)  │
│  Docker (Nginx + Node)      │  │  server/api/web/mp/         │
│  .output/public/*           │  │  · 약 25개 엔드포인트         │
│                             │  │  · proxy-request.ts         │
│                             │  │  · Cookie 자동 전달          │
└─────────────────────────────┘  └────────────┬────────────────┘
                                              │ ③ 사용자 쿠키와 함께
                                              ▼
                                 ┌─────────────────────────────┐
                                 │  위챗 공식계정 백엔드          │
                                 │  mp.weixin.qq.com           │
                                 │  · 글쓰기 검색 API            │
                                 │  · 글 상세 API               │
                                 │  · 댓글/조회수 API            │
                                 └─────────────────────────────┘

5단계 데이터 흐름

[1] 로그인         [2] 검색           [3] 캐싱         [4] 다운로드 큐       [5] 내보내기
─────────         ────────          ────────        ──────────────        ─────────────
사용자가          apis/index.ts     Dexie가         p-queue가             Exporter가
위챗 백엔드   →   가 Nitro 프록시 →  IndexedDB에  →  동시 5개씩         →  HTML/MD/Excel
QR 로그인         호출               글 메타데이터     다운로드               /DOCX로 변환
                                    저장             (rate limit)         후 JSZip 패키징

패턴 1 — 브라우저 측 크롤링 (Client-Side Scraping)

일반 크롤러는 서버에서 돈다. 하지만 그러면 (1) 운영자가 모든 사용자 쿠키 보관, (2) 위챗이 한 IP의 요청이라 차단 쉬움, (3) 계정 공유 윤리 문제까지 셋이 한꺼번에 터진다. 이 프로젝트는 각 사용자 브라우저가 자기 자신의 쿠키로 직접 요청하게 해서 이 셋을 모두 해결한다. 서버는 그저 CORS만 뚫어주는 얇은 프록시.

패턴 2 — Composables (Vue 3의 핵심 재사용 단위)

// composables/useDownloader.ts
export function useDownloader() {
  const queue = new PQueue({ concurrency: 5 });
  const progress = ref(0);

  async function download(article) {
    await queue.add(() => Downloader.fetch(article));
    progress.value++;
  }

  return { download, progress };
}

React의 커스텀 훅과 같은 개념. UI 컴포넌트에서 const { download, progress } = useDownloader()만 부르면 다운로드 로직을 재사용할 수 있다. Nuxt 3는 composables/ 폴더 안의 함수를 자동 임포트해주기 때문에 import 문도 필요 없다.

패턴 3 — 다층 캐싱 (Multi-Layer Caching)

브라우저 메모리 (Vue ref/reactive)
       ↓ 페이지 새로고침 시 유지 X
IndexedDB (Dexie) — store/v2/db.ts
       ↓ 같은 브라우저면 영구 보관
Cloudflare KV / FileSystem KV — NITRO_KV
       ↓ 서버 측 캐싱 (인기 검색 결과)
위챗 원본 API

요청 횟수를 줄이고 위챗의 rate limit을 피하기 위한 핵심 전략. 같은 글을 또 봐도 위챗 서버까지 가지 않고 IndexedDB에서 바로 꺼낸다.

패턴 4 — 환경별 KV 어댑터 (Storage Driver Pattern)

// nuxt.config.ts
nitro: {
  storage: {
    kv: {
      driver: process.env.NITRO_KV_DRIVER || 'memory',
      base: process.env.NITRO_KV_BASE,
    }
  }
}

같은 코드가 환경 변수만 바꾸면 메모리·파일시스템·Cloudflare KV에서 모두 돈다. Nitro의 unstorage 추상화 덕분. 한 번 익혀두면 다양한 배포 환경을 쉽게 다룰 수 있다.

레포 구조 해부

어디에 뭐가 있는지.

wechat-article-exporter/
├── app.vue                       # 최상위 Vue 컴포넌트 (라우터 진입점)
├── pages/
│   ├── index.vue                 # 진입점 라우트
│   ├── dashboard.vue             # SPA 메인 화면
│   ├── dashboard/                # dashboard 하위 라우트 디렉토리
│   └── dev/                      # 개발용 라우트 디렉토리
│
├── apis/                         # 클라이언트용 API 함수 (getArticleList 등)
├── composables/                  # useDownloader, useExporter, useBatchDownload
├── components/                   # Vue 재사용 컴포넌트 (글 카드, 다운로드 버튼)
│
├── server/
│   ├── api/web/mp/               # Nitro의 ~25개 프록시 엔드포인트
│   └── utils/proxy-request.ts    # 위챗 API 호출의 핵심 프록시 로직
│
├── utils/
│   └── download/
│       ├── Downloader.ts         # p-queue 기반 동시 다운로드 매니저
│       └── Exporter.ts           # HTML/MD/Excel/DOCX 변환·패키징
│
├── store/
│   └── v2/db.ts                  # Dexie 스키마 정의 (10개 테이블)
│
├── shared/                       # 클라이언트·서버 공용 유틸 (HTML 파싱)
├── types/                        # AppMsgEx, AccountInfo 등 TS 타입
├── config/                       # 상수, 공개 API 엔드포인트, AG Grid 설정
├── public/vendors/               # html-docx-js 같은 외부 JS (defer 로드)
│
├── nuxt.config.ts                # 모듈·런타임·Nitro·Sentry·Umami 설정
├── Dockerfile                    # node:22-alpine 빌드 → slim+Chromium 실행
├── biome.json                    # Biome 포맷터 설정 (lint 비활성, 행폭 120)
└── CLAUDE.md                     # Claude Code용 컨텍스트 가이드

분야별 배울 것

기술 영역마다 무엇을 가져갈지.

Nuxt 3 / Vue 3 Composition API

Nitro 서버 엔진

IndexedDB + Dexie

Docker 멀티스테이지 빌드

Cloudflare Pages / Workers KV

동시성 제어 (p-queue)

하드웨어 · 시스템 요구사항

배포 모드별 최소 사양.

Docker 셀프호스팅 상세

직접 해볼 수 있는 6단계

난이도별 실습 — Easy → Hard.

실습 1 — 온라인 사이트 한 번 써보기Easy

실습 2 — 레포 로컬에서 띄우기Easy

# Node 22 이상 필수
corepack enable
corepack prepare yarn@1.22.22 --activate

git clone https://github.com/wechat-article/wechat-article-exporter.git
cd wechat-article-exporter
yarn
yarn dev
# → http://localhost:3000

실습 3 — Docker로 셀프 호스팅Medium

실습 4 — 새로운 export 포맷 추가Medium

실습 5 — Cloudflare Pages에 직접 배포Hard

실습 6 — 다른 플랫폼 어댑터 만들기Hard

5주 심화 학습 로드맵

주차별로 따라가면 전체 스택 마스터.

핵심 용어 한눈에

자주 마주칠 단어들.

더 깊이 파고들 자료

공식 · 학습 리소스 · 관전 포인트.

이 레포 관련

• GitHub — wechat-article/wechat-article-exporter
• 온라인 데모 사이트 (down.mptext.top)
• 공식 문서 (docs.mptext.top)
• TrendShift 페이지

기술별 학습 자료

• Nuxt 3 공식 문서 · Vue 3 공식 가이드
• Nitro 공식 · unstorage
• Dexie 공식 사이트 · p-queue GitHub
• Biome 공식 · Cloudflare Pages 문서
• Docker 멀티스테이지 빌드
• Tailwind CSS · @nuxt/ui v2

인범님이 가져갈 핵심 패턴 3가지