Firefox Add-on (AMO) 배포 가이드

작성일: 2026-04-06 Last Updated: 2026-04-06 대상: Firefox Add-ons (addons.mozilla.org, AMO)

공통 문서 참조: CI/CD 파이프라인은 ../common/ci-cd.md, Chrome 배포는 chrome-store.md 참조

1. AMO 개발자 등록

등록 절차

단계	작업	비용
1	Firefox 계정 생성	무료
2	addons.mozilla.org 접속	-
3	개발자 동의서 수락	무료
4	확장 업로드	무료

Chrome Web Store와 달리 등록비 없음. 무료로 배포 가능.

Self-Distribution vs AMO 배포

옵션	설명	자동 업데이트
AMO Listed	AMO에 리스팅 (검색 가능)	O (AMO 통해)
AMO Unlisted	AMO에서 서명만 (검색 불가)	X (직접 구현)
Self-Distribution	자체 서버에서 배포	X (update_url 필요)

중요: Firefox는 AMO 서명 없이는 일반 사용자 설치 불가 (개발자/Nightly 제외).

2. Firefox vs Chrome API 차이점

API 호환성 매트릭스

API	Chrome	Firefox	차이점
`chrome.storage`	O	O	동일
`chrome.alarms`	O	O	동일
`chrome.tabs`	O	O	일부 옵션 차이
`chrome.scripting`	O	O	MV3에서 동일
`chrome.sidePanel`	O	O (MV3)	Firefox는 `sidebar_action` 대신 `sidePanel` (125+)
`chrome.action`	O	O (MV3)	MV2: `browser_action`
`chrome.offscreen`	O	X	Firefox 미지원, 대안 필요
`chrome.declarativeNetRequest`	O	O	규칙 수 제한 차이
`chrome.userScripts`	O	O	Firefox가 먼저 지원
Service Worker (Background)	O (MV3)	O (MV3)	Firefox 120+에서 지원
Background Page (persistent)	X (MV3)	O (MV2)	Firefox MV2는 여전히 유효

Firefox 전용 API

API	용도	Chrome 대안
`browser.browserSettings`	브라우저 설정 접근	없음
`browser.pkcs11`	하드웨어 보안 모듈	없음
`browser.dns`	DNS 조회	없음
`browser.proxy`	프록시 설정 (고급)	제한적

Chrome 전용 API (Firefox 미지원)

API	용도	Firefox 대안
`chrome.offscreen`	DOM API 백그라운드 사용	Background Page (MV2) 또는 별도 탭
`chrome.enterprise.*`	기업 관리	없음
`chrome.instanceID`	푸시 알림	Firefox Push API
`chrome.gcm`	Google Cloud Messaging	Web Push API

Manifest 차이점

// Chrome manifest.json (MV3)
{
  "manifest_version": 3,
  "background": {
    "service_worker": "background.js",
    "type": "module"
  }
}

// Firefox manifest.json (MV3, Firefox 120+)
{
  "manifest_version": 3,
  "background": {
    "scripts": ["background.js"],
    "type": "module"
  },
  "browser_specific_settings": {
    "gecko": {
      "id": "extension@example.com",
      "strict_min_version": "120.0"
    }
  }
}

핵심 차이: Firefox MV3는 service_worker 대신 scripts 배열을 사용. Firefox에서도 Service Worker 방식으로 동작하지만 선언 방식이 다름.

3. browser vs chrome 네임스페이스

문제

Chrome: chrome.* (콜백 기반, MV3에서 Promise도 지원)
Firefox: browser.* (Promise 기반), chrome.*도 호환 지원
Edge: chrome.* (Chrome과 동일)

해결 방법 1: WXT 사용 (권장)

// WXT는 자동으로 브라우저별 네임스페이스 처리
// entrypoints/background.ts
export default defineBackground(() => {
  // WXT가 내부적으로 polyfill 처리
  browser.storage.local.get('key').then((result) => {
    console.log(result);
  });
});

해결 방법 2: webextension-polyfill

npm install webextension-polyfill
npm install -D @types/webextension-polyfill

// lib/browser.ts
import browser from 'webextension-polyfill';

// Chrome에서도 browser.* (Promise 기반)로 통일
const result = await browser.storage.local.get('key');
const tabs = await browser.tabs.query({ active: true, currentWindow: true });

해결 방법 3: Feature Detection (최소 의존성)

// lib/browser-compat.ts
const api = typeof browser !== 'undefined' ? browser : chrome;

// Promise 래퍼 (chrome.* 콜백 → Promise 변환)
function promisify<T>(method: Function, ...args: unknown[]): Promise<T> {
  return new Promise((resolve, reject) => {
    method(...args, (result: T) => {
      if (chrome.runtime.lastError) {
        reject(new Error(chrome.runtime.lastError.message));
      } else {
        resolve(result);
      }
    });
  });
}

네임스페이스 전략 비교

방법	장점	단점	권장
WXT	자동 처리, 빌드 최적화	WXT 의존	O (프로젝트 기본)
webextension-polyfill	표준, 안정적	번들 크기 증가 (~20KB)	O (WXT 미사용 시)
Feature Detection	의존성 없음	직접 유지보수 필요	X

4. Manifest V3 Firefox 대응

Firefox MV3 지원 현황 (2026 기준)

기능	최소 버전	상태
Manifest V3 기본	Firefox 109	안정
Background Service Worker	Firefox 120	안정
`declarativeNetRequest`	Firefox 113	안정
`scripting` API	Firefox 102	안정
`sidePanel` API	Firefox 125	안정
Event Pages (MV3 대안)	Firefox 109	안정

MV2에서 MV3 전환

Firefox는 MV2를 Chrome보다 오래 지원할 예정이나, MV3 통일 권장.

// MV2 (레거시)
{
  "manifest_version": 2,
  "browser_action": { "default_popup": "popup.html" },
  "background": {
    "scripts": ["background.js"],
    "persistent": false
  },
  "permissions": ["*://api.example.com/*"]
}

// MV3 (권장)
{
  "manifest_version": 3,
  "action": { "default_popup": "popup.html" },
  "background": {
    "scripts": ["background.js"],
    "type": "module"
  },
  "permissions": [],
  "host_permissions": ["https://api.example.com/*"]
}

주요 마이그레이션 포인트

MV2	MV3	비고
`browser_action` / `page_action`	`action`	통합
`background.scripts` (persistent)	`background.scripts` (event-driven)	Firefox는 scripts 유지
`permissions`에 호스트 포함	`host_permissions` 분리	권한 분리
`tabs` 권한으로 URL 접근	`activeTab` 또는 `host_permissions`	최소 권한
`browser.webRequest.onBeforeRequest` (blocking)	`declarativeNetRequest`	선언적 네트워크
`content_security_policy` (문자열)	`content_security_policy.extension_pages` (객체)	구조 변경

5. AMO 심사 기준

심사 유형

유형	소요 시간	대상
자동 심사	수 분	모든 제출 (정적 분석)
수동 심사	수 일-수 주	플래그된 확장, 신규, 복잡한 코드

자동 심사 검출 항목

검출 대상	심각도	설명
`eval()` / `new Function()`	경고-거절	동적 코드 실행
`innerHTML` (사용자 입력)	경고	XSS 위험
난독화 코드	거절	판독 불가 코드 금지
알려진 멀웨어 패턴	거절	블랙리스트 패턴
외부 스크립트 로드	거절	원격 코드 실행
불필요 권한	경고	코드에서 미사용 권한

수동 심사 중점 항목

항목	심사 내용
데이터 수집	수집하는 데이터와 목적이 프라이버시 정책과 일치하는지
네트워크 요청	어디로, 어떤 데이터를 전송하는지
권한 사용	선언된 권한이 실제 코드에서 모두 사용되는지
제3자 라이브러리	알려진 취약점 없는지, 라이선스 적절한지
사용자 경험	기만적 행위 없는지

AMO vs CWS 심사 비교

항목	AMO (Firefox)	CWS (Chrome)
등록비	무료	$5
소스코드 제출	필수 (빌드 도구 사용 시)	X
난독화	엄격 금지	금지 (minify는 허용)
코드 리뷰 깊이	상대적으로 깊음	자동화 중심
심사 속도	느림 (수 일-수 주)	빠름 (수 시간-수 일)
재심사 요청	가능	가능
Self-Distribution	서명 후 가능	X (CWS 전용)

6. 소스코드 제출 요구사항

언제 소스코드 제출이 필요한가

조건	소스코드 제출
Webpack/Vite/Rollup 등 번들러 사용	필수
TypeScript 사용	필수
빌드 과정 없는 순수 JS	불필요
minification만 적용	필수

소스코드 제출 가이드

# 제출물 구조 (ZIP)
source-code.zip
+-- package.json
+-- package-lock.json          # 정확한 의존성 버전
+-- tsconfig.json
+-- wxt.config.ts              # 또는 vite.config.ts 등
+-- src/                       # 소스코드 전체
+-- README.md                  # 빌드 방법 (아래 템플릿)

빌드 안내 README 템플릿

# Build Instructions

## Prerequisites
- Node.js 20.x
- npm 10.x

## Steps
1. Install dependencies:
   ```bash
   npm ci

Build the extension:
```
npm run build
```
The built extension will be in .output/firefox-mv3/

Environment

OS: Ubuntu 22.04 (or any Node.js 20+ compatible OS)
No additional system dependencies required

### 핵심 규칙

| 규칙 | 설명 |
|------|------|
| **재현 가능한 빌드** | 소스에서 동일한 출력물 생성 가능해야 함 |
| **모든 의존성 포함** | `package-lock.json` / `yarn.lock` 필수 |
| **비밀키 제거** | API 키, 시크릿 등 제거 후 제출 |
| **빌드 도구 명시** | Node.js 버전, npm/yarn 버전 명시 |
| **빌드 명령 명시** | `npm ci && npm run build` 형태 |

### 난독화 정책

```javascript
// ❌ 거절: 난독화 (코드를 읽을 수 없게 변환)
var _0x1a2b=['log','Hello'];(function(_0x2d8f05,_0x4b81bb){...

// ✅ 허용: Minification (공백/줄바꿈 제거, 변수명 축소)
function a(b,c){return b+c}console.log(a(1,2));

// ✅ 허용: Tree-shaking (미사용 코드 제거)
// ✅ 허용: Bundling (파일 합치기)

7. Firefox Android 지원

지원 현황

Firefox for Android는 제한된 확장만 지원. AMO에서 별도 호환성 선언 필요.

Android 호환성 선언

// manifest.json
{
  "browser_specific_settings": {
    "gecko": {
      "id": "extension@example.com",
      "strict_min_version": "120.0"
    },
    "gecko_android": {
      "strict_min_version": "120.0"
    }
  }
}

Android에서 제한되는 API

API	데스크톱	Android	대안
`sidePanel`	O	X	Popup 사용
`devtools`	O	X	없음
`windows`	O	제한적	`tabs` 사용
`contextMenus`	O	제한적	Popup 내 메뉴
`browserAction.openPopup`	O	X	사용자 클릭

반응형 UI 처리

/* Popup/Options - 모바일 화면 대응 */
:root {
  --popup-width: 360px;
  --popup-max-height: 600px;
}

@media (max-width: 400px) {
  /* Firefox Android Popup */
  :root {
    --popup-width: 100vw;
    --popup-max-height: 100vh;
  }
}

// 모바일 여부 감지
async function isAndroid(): Promise<boolean> {
  const platformInfo = await browser.runtime.getPlatformInfo();
  return platformInfo.os === 'android';
}

// 모바일에서 미지원 기능 분기
if (await isAndroid()) {
  // Popup 기반 UI
} else {
  // Side Panel 기반 UI
}

8. 배포 자동화 (web-ext)

web-ext CLI

# 설치
npm install -D web-ext

# 개발 모드 (실시간 리로드)
web-ext run --source-dir .output/firefox-mv3 --firefox-profile dev

# Lint (AMO 심사 규칙 기반)
web-ext lint --source-dir .output/firefox-mv3

# 빌드 (ZIP 생성)
web-ext build --source-dir .output/firefox-mv3 --overwrite-dest

# 서명 (Unlisted, self-distribution용)
web-ext sign \
  --source-dir .output/firefox-mv3 \
  --api-key $AMO_JWT_ISSUER \
  --api-secret $AMO_JWT_SECRET

AMO API 키 발급

1. addons.mozilla.org 로그인
2. Tools → Developer Hub → Manage API Keys
3. JWT Issuer + JWT Secret 생성
4. CI/CD 시크릿에 등록:
   - AMO_JWT_ISSUER
   - AMO_JWT_SECRET

GitHub Actions 워크플로우

# .github/workflows/release-firefox.yml
name: Release to Firefox Add-ons

on:
  push:
    tags:
      - 'v*'

permissions:
  contents: read

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
          cache-dependency-path: platform/client/browser-ext/package-lock.json

      - name: Install dependencies
        run: npm ci
        working-directory: platform/client/browser-ext

      - name: Build for Firefox
        run: npm run build -- --browser firefox
        working-directory: platform/client/browser-ext

      - name: Lint with web-ext
        run: npx web-ext lint --source-dir .output/firefox-mv3
        working-directory: platform/client/browser-ext

      - name: Package source code
        run: |
          zip -r source-code.zip . \
            -x "node_modules/*" \
            -x ".output/*" \
            -x ".git/*" \
            -x ".env*"
        working-directory: platform/client/browser-ext

      - name: Upload to AMO
        run: |
          npx web-ext sign \
            --channel listed \
            --source-dir .output/firefox-mv3 \
            --api-key ${{ secrets.AMO_JWT_ISSUER }} \
            --api-secret ${{ secrets.AMO_JWT_SECRET }} \
            --upload-source-code source-code.zip
        working-directory: platform/client/browser-ext

로컬 개발 팁

# Firefox 프로필 관리 (개발 전용)
web-ext run \
  --source-dir .output/firefox-mv3 \
  --firefox-profile ext-dev \
  --profile-create-if-missing \
  --keep-profile-changes

# 특정 Firefox 버전으로 테스트
web-ext run \
  --source-dir .output/firefox-mv3 \
  --firefox /path/to/firefox-nightly

# Android 에뮬레이터 테스트
web-ext run \
  --source-dir .output/firefox-mv3 \
  --target firefox-android \
  --adb-device emulator-5554

9. 체크리스트

AMO 제출 전 체크리스트

매니페스트:

browser_specific_settings.gecko.id 설정 (이메일 형식 또는 UUID)
strict_min_version 적절히 설정
Firefox MV3 문법 사용 (scripts 배열, service_worker 아님)
Chrome 전용 API 사용 여부 확인 (offscreen 등)

코드:

eval() / new Function() 없음
난독화 없음 (minification은 허용)
외부 스크립트 로드 없음
innerHTML에 사용자 입력 직접 할당 없음
web-ext lint 통과

소스코드:

빌드 도구 사용 시 소스코드 ZIP 준비
README에 빌드 방법 명시
package-lock.json / yarn.lock 포함
API 키/시크릿 제거
소스에서 동일 출력물 빌드 가능 확인

프라이버시:

프라이버시 정책 URL 준비
데이터 수집 항목 고지

호환성:

Firefox 최소 지원 버전에서 테스트
Firefox Android 지원 시 모바일 UI 테스트
browser.* 네임스페이스 호환 (polyfill 또는 WXT)

배포:

AMO JWT 키 발급 및 CI 시크릿 등록
web-ext sign 테스트 (Unlisted로 먼저)
버전 번호 증가 확인

문서	내용
chrome-store.md	Chrome Web Store 배포
safari-extension.md	Safari Web Extension 배포
cross-browser.md	크로스 브라우저 호환성
architecture.md	Manifest V3 아키텍처
../common/ci-cd.md	공통 CI/CD 파이프라인
../common/security.md	공통 보안 가이드

목차​

1. AMO 개발자 등록​

등록 절차​

Self-Distribution vs AMO 배포​

2. Firefox vs Chrome API 차이점​

API 호환성 매트릭스​

Firefox 전용 API​

Chrome 전용 API (Firefox 미지원)​

Manifest 차이점​

3. browser vs chrome 네임스페이스​

문제​

해결 방법 1: WXT 사용 (권장)​

해결 방법 2: webextension-polyfill​

해결 방법 3: Feature Detection (최소 의존성)​

네임스페이스 전략 비교​

4. Manifest V3 Firefox 대응​

Firefox MV3 지원 현황 (2026 기준)​

MV2에서 MV3 전환​

주요 마이그레이션 포인트​

5. AMO 심사 기준​

심사 유형​

자동 심사 검출 항목​

수동 심사 중점 항목​

AMO vs CWS 심사 비교​

6. 소스코드 제출 요구사항​

언제 소스코드 제출이 필요한가​

소스코드 제출 가이드​

빌드 안내 README 템플릿​

Environment​

7. Firefox Android 지원​

지원 현황​

Android 호환성 선언​

Android에서 제한되는 API​

반응형 UI 처리​

8. 배포 자동화 (web-ext)​

web-ext CLI​

AMO API 키 발급​

GitHub Actions 워크플로우​

로컬 개발 팁​

9. 체크리스트​

AMO 제출 전 체크리스트​

관련 문서​

목차

1. AMO 개발자 등록

등록 절차

Self-Distribution vs AMO 배포

2. Firefox vs Chrome API 차이점

API 호환성 매트릭스

Firefox 전용 API

Chrome 전용 API (Firefox 미지원)

Manifest 차이점

3. browser vs chrome 네임스페이스

문제

해결 방법 1: WXT 사용 (권장)

해결 방법 2: webextension-polyfill

해결 방법 3: Feature Detection (최소 의존성)

네임스페이스 전략 비교

4. Manifest V3 Firefox 대응

Firefox MV3 지원 현황 (2026 기준)

MV2에서 MV3 전환

주요 마이그레이션 포인트

5. AMO 심사 기준

심사 유형

자동 심사 검출 항목

수동 심사 중점 항목

AMO vs CWS 심사 비교

6. 소스코드 제출 요구사항

언제 소스코드 제출이 필요한가

소스코드 제출 가이드

빌드 안내 README 템플릿

Environment

7. Firefox Android 지원

지원 현황

Android 호환성 선언

Android에서 제한되는 API

반응형 UI 처리

8. 배포 자동화 (web-ext)

web-ext CLI

AMO API 키 발급

GitHub Actions 워크플로우

로컬 개발 팁

9. 체크리스트

AMO 제출 전 체크리스트

관련 문서