배포

zip 직접 전달, Web Store 업로드, self-host .crx와 update_url 세 가지의 장단점, .pem 키 관리, 그리고 chrome이 외부 .crx를 차단하는 것을 어떻게 우회하는지를 봅니다. build-and-package에서 dist/와 packages/extension.zip을 만들었다는 가정 위에서 시작합니다.

build-and-package 까지가 도구가 자동으로 해 주는 영역입니다. 채널 선택, .pem 키 보관, 호스팅 도메인 결정, 스토어 검수 대응은 전부 자동화 밖입니다. .pem 키와 결제와 검수 계정은 사용자 자격으로 움직여야 하는 자산이라, 도구가 그것을 대신 실행하면 키 유출과 정책 사고가 따라옵니다. 그래서 여기부터는 본인이 직접 합니다.

세 경로 한눈에

경로	받는 쪽 절차	자동 업데이트	검수	적합한 경우
zip 직접 전달	압축 해제 후 chrome://extensions에서 Load unpacked	없음	없음	동료 한두 명, 사내 PoC
Web Store 업로드	스토어에서 한 번 클릭	있음 (스토어가 처리)	있음, 수일에서 수주	일반 공개
self-host .crx + update_url	한 번 설치 후 자동	있음 (update.xml 갱신)	없음	사내 배포, 통제된 사용자군

세 경로는 배타적이지 않습니다. 같은 확장을 사내에는 self-host로, 일반 사용자에게는 Web Store로 동시에 배포할 수도 있습니다. 한쪽을 끊고 다른 쪽으로 넘기는 마이그레이션도 흔합니다.

zip 직접 전달

pnpm run package가 만든 packages/extension.zip을 그대로 보냅니다. 받는 쪽은 압축을 풀고 chrome://extensions에서 개발자 모드를 켠 다음 “Load unpacked”로 그 폴더를 지정합니다. 업데이트는 새 zip을 같은 절차로 다시 설치합니다. 자동 갱신은 없습니다.

PoC 단계에서는 충분하지만, 받는 쪽이 매번 같은 동작을 반복해야 합니다. 사용자가 다섯 명을 넘어가기 시작하면 self-host로 넘깁니다.

Web Store 업로드

업로드 직전에 갖춰야 할 것은 짧습니다.

• 일관된 아이콘 16, 32, 48, 128. 보통 public/icons/ 아래에 둡니다
• store listing 용 스크린샷 1280×800 또는 640×400을 준비합니다
• 한 줄 설명과 자세한 설명. 권한이 왜 필요한지 명시합니다. 특히 host_permissions는 거부 사유 1순위입니다
• 비공개 배포 옵션. 검수 전에 테스터 한정으로 먼저 배포할 수도 있습니다

스크린샷 캡처 가이드와 store 콘텐츠 작성 절차는 expert 트랙에서 다루지 않습니다. 화면을 보면서 따라가야 하는 단계라 비개발자용 매뉴얼 distribution에 같은 주제가 다른 방식으로 정리돼 있습니다.

self-host .crx

가장 손이 많이 가는 방법이지만 통제가 필요한 사내 배포에서는 이 경로를 고릅니다.

.crx 만들기와 .pem 키

첫 .crx를 만들 때 chrome이 함께 만들어 주는 .pem 키 한 장이 그 확장의 신원이 됩니다. 같은 키로 서명한 .crx만 chrome이 같은 확장으로 인식합니다. 키를 잃어버리면 같은 확장으로 업데이트할 수 없습니다. 사용자 전원에게 새 확장으로 다시 설치해 달라고 안내해야 한다는 뜻입니다.

키는 git에 커밋하지 않습니다. 1Password 또는 팀 비밀 저장소에 두고, 회전 정책을 ADR 한 장에 적어 둡니다. docs/adr/에 enterprise policy 채택 결정과 키 회전 절차가 한 장 들어 있습니다.

update_url과 update.xml

manifest에 update_url을 한 줄 추가합니다.

"update_url": "https://example.com/extension/update.xml"

update.xml은 chrome이 정의한 형식이 있습니다.

<?xml version='1.0' encoding='UTF-8'?>
<gupdate xmlns='http://www.google.com/update2/response' protocol='2.0'>
  <app appid='YOUR_EXTENSION_ID'>
    <updatecheck codebase='https://example.com/extension/extension-1.2.0.crx' version='1.2.0' />
  </app>
</gupdate>

새 버전을 배포할 때는 .crx를 같은 host의 새 경로에 올리고 update.xml의 version과 codebase만 갱신합니다. chrome이 하루 한 번 정도 update_url을 폴링하면서 새 버전을 받아 갑니다. host 는 GitHub Pages, S3, 자체 도메인 어디든 정적 파일 서빙이 되면 됩니다.

chrome의 외부 .crx 차단

기본 정책으로 chrome은 Web Store가 아닌 곳에서 받은 .crx의 설치를 막습니다. 사내 배포에서 이 제한을 해제하는 방법은 두 가지입니다.

• enterprise policy의 ExtensionInstallAllowlist 또는 ExtensionInstallForcelist에 확장 ID와 update_url을 등록합니다. Windows는 레지스트리, macOS는 plist, Linux는 /etc/opt/chrome/policies/managed/의 JSON으로 적습니다.
• 사용자가 unpacked로 직접 설치하게 합니다. 이 경우 자동 업데이트는 비활성화됩니다.

ID 등록과 도메인 결정은 한 번 정하면 되돌리기 어렵습니다. 그래서 이 결정도 ADR 한 장으로 남깁니다. 어떤 도메인에서 update.xml을 호스팅할지, 키 회전 주기를 어떻게 잡을지가 거기에 들어 있습니다.

expert tier 끝

여기까지가 chrome-ext-base의 expert tier입니다. intro에서 guardrail 세 개를 짚고, architecture에서 의존 방향과 메시지 라우팅을 봤고, build-and-package에서 dist와 zip이 어떻게 만들어지는지를 본 다음, 여기서 그 산출물을 사용자에게 전달하는 세 가지 경로를 나눠 봤습니다.

비개발자 청중을 위한 단계별 안내, 화면 캡처, OS별 설치 분기는 비개발자용 매뉴얼에 같은 주제를 다른 방식으로 풀어 두었습니다.