VS Code & Open VSX 익스텐션 배포 완전 가이드 — VS Code · Cursor · VSCodium 한 번에

VS Code & Open VSX 익스텐션 배포 완전 가이드 — VS Code · Cursor · VSCodium 한 번에

VS Code Marketplace와 Open VSX Registry 양쪽에 동일한 vsix를 배포하는 첫 출시부터 업데이트까지의 완전 가이드

VS Code Marketplace는 vsce publish, Cursor·VSCodium은 Open VSX의 ovsx publish. 두 곳에 같은 vsix를 올리면 끝. PAT 두 개와 Eclipse Foundation 약관 사인이 핵심 셋업이다.

VS Code Marketplace는 Microsoft 소유라 Cursor·VSCodium·Gitpod 같은 비공식 포크에서는 사용할 수 없다. 이 에디터들은 Eclipse Foundation이 운영하는 Open VSX Registry를 사용한다. 따라서 진짜 의미의 "전 사용자 대상 배포"를 하려면 두 마켓 모두에 올려야 한다. 이 글은 한 번에 양쪽 마켓에 배포하기 위한 완전 가이드다.

1. 사전 준비

마켓플레이스 배포에 앞서 package.json에 필수 항목이 채워져 있어야 한다.

{
  "name": "your-extension-name",
  "displayName": "Your Extension Display Name",
  "description": "...",
  "version": "0.1.0",
  "publisher": "your-publisher-id",
  "license": "MIT",
  "icon": "media/icon.png",
  "galleryBanner": {
    "color": "#060810",
    "theme": "dark"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/yourname/yourrepo"
  },
  "engines": { "vscode": "^1.90.0" }
}

주의사항

• publisher.name 조합이 마켓플레이스 전체에서 고유해야 한다. 같은 이름이라도 publisher가 다르면 OK.
• displayName은 중복이 가능하지만, 매우 유사하면 마켓이 경고를 띄울 수 있으니 차별화하는 게 좋다.
• 아이콘은 128×128 PNG 권장 (필수는 아니나 작거나 비율이 다르면 잘릴 수 있음).
• LICENSE 파일은 저장소 루트에 두는 게 표준이다. GitHub 라이선스 자동 인식이 작동하고, 마켓의 라이선스 링크도 그쪽으로 잡힌다.

2. 배포 도구 설치

# VS Code Marketplace용
npm install -g @vscode/vsce

# Open VSX용
npm install -g ovsx

# 또는 npx로 매번 실행 (전역 설치 불필요)
npx vsce ...
npx ovsx ...

Part 1 — VS Code Marketplace 배포

3. Publisher 계정 생성

marketplace.visualstudio.com/manage 접속 → Microsoft 계정 로그인 → Create publisher 클릭

💡 팁: Publisher ID가 선점됐으면 다른 ID로. GitHub 계정명을 권장 — Open VSX쪽과 같은 ID로 통일하기 쉽다.

4. PAT(Personal Access Token) 발급

vsce publish는 Azure DevOps PAT로 인증한다.

4-1. Azure DevOps 조직 생성

dev.azure.com 접속 → Microsoft 계정으로 로그인 → 조직 생성

💡 참고: Azure 구독은 필요 없다. Microsoft 계정만 있으면 Azure DevOps 무료 플랜(5인 이하)에 가입 가능하며, 결제 정보 등록도 필요 없다.

4-2. 토큰 생성

우측 상단 사용자 아이콘 → Personal access tokens → New Token

Create → 토큰 즉시 복사 (창 닫으면 재확인 불가)

⚠️ 토큰은 환경변수(VSCE_PAT)나 시크릿 매니저에 보관할 것. 절대 커밋하거나 채팅·이슈에 붙이지 말 것. 노출되면 즉시 Azure DevOps에서 Revoke.

5. 첫 배포

5-1. VSIX 빌드

npx vsce package --no-dependencies

💡 주의: 모노레포(pnpm/yarn workspace)에서는 --no-dependencies 플래그가 필수다. workspace 프로토콜(workspace:*)을 npm이 invalid로 판단해 에러난다.

5-2. 배포 실행

npx vsce publish --no-dependencies -p $VSCE_PAT

# 또는 vsix 파일 직접 지정
npx vsce publish --no-dependencies --packagePath your-ext-0.1.0.vsix -p $VSCE_PAT

성공 시 아래와 같이 출력된다:

INFO  Publishing 'publisher.extension-name v0.1.0'...
INFO  Extension URL: https://marketplace.visualstudio.com/items?itemName=publisher.extension-name
DONE  Published publisher.extension-name v0.1.0.

⏱️ 소요 시간: 배포 후 마켓 검색 노출까지 5~10분 소요된다.

Part 2 — Open VSX 배포 (Cursor · VSCodium · Gitpod)

6. Open VSX 계정 + Publisher Agreement

Open VSX는 Eclipse Foundation 운영이라 약관 사인이 필수다.

6-1. GitHub OAuth 로그인

open-vsx.org → 우측 상단 Log In → GitHub 로그인 → 우측 상단 아바타 → Settings

6-2. Eclipse Foundation 약관 사인

Profile 페이지에 노란 경고 박스가 뜬다 → Log in with Eclipse 클릭

⚠️ 자주 막히는 지점: 가입 후 "Eclipse profile is missing a GitHub username" 에러가 뜨면, accounts.eclipse.org/user/edit에서 GitHub Username 필드에 본인 GitHub username 입력 후 Save.

Open VSX로 복귀 → Sign Publisher Agreement 클릭

6-3. Access Token 발급

Settings → Access Tokens 탭 → Generate New Token → Description 입력 → Generate → 토큰 즉시 복사 (다시 안 보임)

7. Namespace 생성 + 첫 배포

7-1. Namespace 생성

export OVSX_PAT=<발급받은_토큰>
npx ovsx create-namespace your-publisher-id

💡 Open VSX의 namespace는 VS Code Marketplace의 publisher ID와 동일한 개념이다. VS Code쪽과 같은 ID로 생성 권장. 누가 선점했으면 다른 이름을 써야 하지만 양쪽 ID가 분리되니 비추.

7-2. 배포 실행

# 기존 vsix 재활용 — 양쪽 마켓에 동일 바이너리 보장
npx ovsx publish your-ext-0.1.0.vsix

성공 시:

🚀  Published publisher.extension-name v0.1.0

⏱️ Open VSX 페이지 반영 1~5분, Cursor 검색 반영 5~15분.

8. Verified Publisher 신청 (선택)

Open VSX에 publish하면 Cursor에서 설치 시 다음과 같은 경고 toast가 뜬다:

"That user account is not a verified publisher of the namespace..."

설치·작동에는 지장 없지만 신뢰감을 위해 verified 마크를 받으려면:

1. github.com/EclipseFdn/open-vsx.org/issues/new/choose
2. Claim namespace ownership 템플릿 선택
3. 본문에 namespace 소유 근거 작성 — GitHub 계정 = Open VSX 계정 = VS Code publisher 계정 일치 명시 + 본인이 publish한 익스텐션 URL 첨부
4. 운영진 검토 (수일~수주)
5. 머지 후 다음 publish 버전부터 verified 마크 적용 (소급 안 됨)

Part 3 — 양쪽 마켓 동시 운영

9. 업데이트 워크플로

9-1. 버전 올리기

수동 수정:

"version": "0.2.0"

또는 한 줄로 자동 bump + 배포 (vsce가 git tag도 자동 생성):

npx vsce publish patch   # 0.1.0 → 0.1.1
npx vsce publish minor   # 0.1.0 → 0.2.0
npx vsce publish major   # 0.1.0 → 1.0.0

버전은 Semantic Versioning 규칙을 따른다.

9-2. CHANGELOG.md 업데이트

## [0.2.0] — 2026-06-01

### Added
- 새 기능 설명

### Fixed
- 수정된 버그 설명

9-3. 양쪽 마켓 한 번에 배포

package.json의 scripts에 묶어두면 편하다:

"scripts": {
  "publish:vscode": "vsce publish --no-dependencies",
  "publish:openvsx": "ovsx publish --no-dependencies",
  "publish:all": "pnpm publish:vscode && pnpm publish:openvsx"
}

실행:

export VSCE_PAT=xxx
export OVSX_PAT=yyy
pnpm publish:all

💡 두 CLI 모두 VSCE_PAT / OVSX_PAT 환경변수를 자동 인식하므로 -p 플래그 생략 가능.

📢 자동 업데이트: 기존 설치 사용자는 VS Code / Cursor가 자동으로 업데이트 알림을 표시한다.

10. README 뱃지 (양쪽 마켓 표시)

[![VS Marketplace](https://img.shields.io/visual-studio-marketplace/v/publisher.ext-name?label=VS%20Marketplace&color=blue)](https://marketplace.visualstudio.com/items?itemName=publisher.ext-name)
[![Open VSX](https://img.shields.io/open-vsx/v/publisher/ext-name?label=Open%20VSX&color=a60ee5)](https://open-vsx.org/extension/publisher/ext-name)
[![Downloads](https://img.shields.io/visual-studio-marketplace/d/publisher.ext-name)](https://marketplace.visualstudio.com/items?itemName=publisher.ext-name)

⚠️ slug 차이 주의: VS Code 뱃지는 publisher.ext-name (점), Open VSX 뱃지는 publisher/ext-name (슬래시).

11. 트러블슈팅

12. 배포 후 관리

마치며

VS Code 단일 배포는 흔한 가이드가 많지만, Cursor 사용자가 폭증한 2025년 이후 Open VSX 동시 배포는 사실상 필수가 됐다. 한 번 셋업해두면 pnpm publish:all 한 줄로 두 마켓이 동기화되니, 처음 셋업할 때 양쪽 다 같이 해두는 걸 권장한다.

Verified 마크는 신청만 해두고 잊고 지내면 된다. 며칠~몇 주 후 알아서 머지되고, 그 이후 publish부터 ✓ 표시가 붙는다.