Chrome Storage Sync 올바르게 설정하는 방법

중요: chrome.storage.sync는 사용자의 Google 계정으로 로그인되어 있고 Chrome 동기화가 활성화된 경우에만 기기 간 동기화가 작동합니다. 오프라인일 때는 로컬에 저장되고 이후 온라인 시 동기화됩니다.

Chrome Storage를 올바르게 설정하는 방법을 보여주는 스크린샷

개요

Chrome Storage는 브라우저 확장과 웹앱에 강력한 저장소 기능을 제공합니다. 브라우저의 localStorage가 문자열 기반인 반면, chrome.storage API는 객체(Object)를 직접 다루며 비동기라서 성능과 반응성이 더 좋습니다. chrome.storage에는 주로 두 가지 영역이 있습니다.

chrome.storage.local: 브라우저가 설치된 로컬 머신에 데이터를 저장합니다. 동기화가 되지 않습니다.
chrome.storage.sync: 사용자의 Google 계정과 연결된 Chrome 환경 사이에서 데이터를 동기화합니다(로그인 + 동기화 활성화 필요).

아래에서는 사용법, 차이점, 관리 방법, 문제 해결, 모범 사례, 테스트 케이스, 역할별 체크리스트 등 개발·운영 관점에서 필요한 모든 것을 다룹니다.

핵심 개념 1줄 정의

로컬 스토리지(localStorage): 문자열 기반의 간단한 클라이언트 저장소(동기 API).
chrome.storage.local: 객체 기반, 비동기 저장소(로컬 머신 전용).
chrome.storage.sync: 객체 기반, 비동기 저장소(기기 간 동기화).

chrome.storage와 localStorage 차이(요약)

localStorage: 문자열만 저장 가능. 동기 API이므로 큰 데이터를 다루면 UI가 멈출 수 있음.
chrome.storage: 객체 저장 가능. 비동기로 동작해 성능에 유리.
chrome.storage.sync: 자동 동기화(조건 충족 시). chrome.storage.local: 동기화하지 않음.

Chrome.sync는 localStorage를 동기화하나?

아닙니다. localStorage는 브라우저 로컬에 문자열로 저장되는 표준 Web API입니다. chrome.storage.sync는 Chrome의 확장 API로, 객체 형태의 데이터를 Chrome 계정에 연결된 다른 기기로 동기화합니다. 따라서 localStorage에 있는 데이터는 자동으로 chrome.storage.sync로 동기화되지 않습니다. 동기화를 원한다면 명시적으로 localStorage 데이터를 chrome.storage.sync로 마이그레이션해야 합니다.

chrome.storage 사용법(기본 예제)

아래 예제는 콜백 방식과 프라미스(프로미스) 래퍼를 모두 보여줍니다.

콜백 예제:

// 저장 (sync 또는 local)
chrome.storage.sync.set({ theme: 'dark', fontSize: 14 }, function() {
  if (chrome.runtime.lastError) {
    console.error('저장 오류:', chrome.runtime.lastError);
  } else {
    console.log('저장 완료');
  }
});

// 읽기
chrome.storage.sync.get(['theme', 'fontSize'], function(result) {
  console.log('현재 설정:', result);
});

// 삭제
chrome.storage.sync.remove(['fontSize'], function() {
  console.log('fontSize 삭제 완료');
});

// 모두 삭제
chrome.storage.sync.clear(function() {
  console.log('동기 저장소 초기화 완료');
});

프라미스 래퍼 예제(간단한 util):

function storageGet(area, keys) {
  return new Promise((resolve) => {
    chrome.storage[area].get(keys, (result) => resolve(result));
  });
}

function storageSet(area, items) {
  return new Promise((resolve, reject) => {
    chrome.storage[area].set(items, () => {
      if (chrome.runtime.lastError) reject(chrome.runtime.lastError);
      else resolve();
    });
  });
}

// 사용 예
(async () => {
  await storageSet('sync', { greetings: '안녕하세요' });
  const res = await storageGet('sync', ['greetings']);
  console.log(res.greetings); // '안녕하세요'
})();

참고: Manifest 파일에 storage 권한이 선언되어 있어야 합니다. 예: “permissions”: [“storage”]

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0",
  "permissions": ["storage"]
}

chrome.storage.sync와 chrome.storage.local의 주요 차이(상세)

비동기성: 둘 다 비동기 API입니다. 하지만 네트워크를 통해 동기화되는 chrome.storage.sync는 네트워크 상태와 계정 상태에 영향을 받습니다.
접근 범위: local은 현재 기기만, sync는 로그인된 모든 기기.
데이터 형태: 둘 다 객체를 저장할 수 있습니다(문자열로 변환하는 수작업 불필요).
인코그니토: sync는 확장 설정을 보존(설정에 따라)하며 인코그니토 상태에서도 동작할 수 있는 옵션이 있습니다. (확장 권한/설정에 따라 다름)

localStorage vs Cookies vs Cache 요약 표

항목	용도	용량	보안/특징
Cookies	서버와의 세션/상태 전달(HTTP 요청에 포함됨)	일반적으로 작은 크기(약 4KB 수준)	HTTP 헤더로 전송되므로 서버 측에서 처리 가능. 보안 설정(secure, httpOnly) 가능.
localStorage	클라이언트 전용 데이터 저장(문자열)	일반적으로 쿠키보다 큼	스크립트에서 접근 가능. XSS에 취약할 수 있어 민감정보 저장 금지 권고.
Cache (브라우저 캐시)	리소스(이미지/스크립트) 재사용으로 성능 향상	바이트 단위, 리소스별 정책	네트워크 효율화 목적. 민감정보 저장 금지.

노트: 보안상 이유로 비밀번호나 신용카드 같은 민감한 정보를 브라우저 저장소에 보관하지 마십시오. 민감 정보는 서버 측 안전한 저장소 또는 플랫폼 제공 암호화 기능을 이용하세요.

Chrome에서 저장소 관리(사용자 가이드)

1) 브라우저에서 기본적으로 데이터 지우기(모든 도메인)

Chrome을 열고 우측 상단의 세로 점 3개 메뉴를 클릭합니다.
[도구 더보기] > [인터넷 사용 기록 삭제]를 클릭합니다.
시간 범위를 선택하고 삭제할 항목(검색 기록, 쿠키 및 기타 사이트 데이터, 캐시된 이미지 및 파일 등)을 선택합니다.
[데이터 삭제]를 클릭합니다.

단축키: Windows/Linux에서는 Ctrl+Shift+Delete, macOS에서는 Command+Shift+Delete

2) 사이트별 저장 데이터 삭제(권한 포함)

Chrome 설정 > 개인정보 및 보안 > 사이트 설정으로 이동합니다.
[사이트에 저장된 권한 및 데이터 보기]를 클릭합니다.
[모든 데이터 삭제] 버튼을 눌러 사이트별 데이터를 제거하거나 개별 사이트를 선택 후 삭제합니다.

3) 개발자 도구로 localStorage 직접 삭제

확장 프로그램의 백그라운드 페이지 또는 목적 사이트를 엽니다.
Chrome 메뉴 > 도구 더보기 > 개발자 도구를 엽니다.
Application 탭을 선택합니다.
우측 패널에서 Local Storage를 확장한 뒤 해당 도메인을 우클릭하여 Clear를 선택합니다.

이미지 ALT 설명(모두 한국어로 변경됨):
/files/01459716-de82-4bbf-977a-d42bafcc2e73.png: Chrome 우측 상단 메뉴(세로 점 3개) 스크린샷
/files/24ad7d07-75b3-454f-a83d-ddd916b57116.png: 도구 더보기 > 인터넷 사용 기록 삭제 메뉴 스크린샷
/files/e0008159-8005-4968-98a9-8c101f79d328.jpg: 인터넷 사용 기록 삭제 대화상자 예시 스크린샷
/files/84da6e27-900f-42de-bc25-19445bcd606e.png: Chrome 설정 메뉴 스크린샷
/files/3691bae2-1b88-4969-918c-db2ef3e2d9da.png: 설정 항목 리스트 스크린샷
/files/680b6c50-8429-437c-8887-5490205f123f.png: 개인정보 및 보안 섹션 스크린샷
/files/0d92f203-e01f-42f5-8648-33ca62193f92.png: 사이트 설정 메뉴 스크린샷
/files/ec264bf7-5f2a-46bd-a6ae-fb631074a8c2.png: 사이트 권한 및 저장 데이터 보기 스크린샷
/files/2e4af095-27bf-453a-852d-a82656a35b45.jpg: 모든 데이터 삭제 확인 버튼 스크린샷
/files/932f72ca-57e0-4af9-88a9-39352c8e86e9.jpg: 삭제 확인 대화상자 스크린샷
/files/106f9df2-32ff-4d25-a2c5-c08ceb437ea4.png: 쿠키 및 기타 사이트 데이터 설정 스크린샷
/files/9a74b0ea-02b1-451c-bb9b-c8ab2d0930dd.png: 창 닫을 때 쿠키 및 사이트 데이터 삭제 토글 스크린샷
/files/d4d64b31-53ea-4953-bb9b-83998d8fc5c7.jpg: 사이트별 쿠키 예외 설정 스크린샷
/files/9ec361f0-1d47-489c-bade-620579e56587.png: 개발자 도구 - Application 탭 스크린샷
/files/50cdc089-1f03-4424-86b6-8015c9b81f10.png: Application 탭의 Local Storage 섹션 스크린샷
/files/880364fd-3c23-410f-83cd-775895e97c3f.png: Local Storage 항목 우클릭 후 Clear 스크린샷

저장소 위치(로컬 파일 경로)

Chrome은 사용자 프로파일 폴더에 웹 데이터를 저장합니다. 예: Windows에서는 일반적으로 다음 경로 아래에 로컬 스토리지 파일이 존재합니다.

%USERPROFILE%\AppData\Local\Google\Chrome\User Data\Default\Local Storage

(운영체제 및 프로파일 이름에 따라 경로는 달라질 수 있습니다.)

chrome.storage.sync.set 동작하지 않을 때 점검 항목(체크리스트)

manifest.json에 storage 권한이 선언되었는가? (필수)
사용자가 Chrome에 로그인되어 있고 Chrome 동기화가 활성화되어 있는가?
chrome.runtime.lastError를 확인했는가? 비동기 콜백에서 lastError로 실패 원인을 확인할 수 있습니다.
데이터를 한 번에 너무 많이 넣으려 하지 않았는가? sync에는 용량 제한(quota)이 있습니다.
키/값 형식을 올바르게 전달했는가? chrome.storage.sync.set({ myKey: value }) 형태여야 합니다.
여러 값을 한 번에 잘못 전달하지는 않았는가? (객체 형태로 전달해야 함)
프로필 권한 또는 OS 차원의 파일 접근 권한이 필요한 환경인지 확인(앱 권한)하세요.
네트워크나 계정 동기화 문제라면 Chrome의 동기화 재설정(Reset Sync)을 시도해 보세요.

자주 발생하는 원인과 해결법

권한 누락: manifest에 storage 권한을 추가하면 해결됩니다.
비동기 처리 미숙: 콜백을 사용하거나 프라미스 래퍼를 쓴 뒤 실패를 로깅하세요.
용량 문제: 데이터를 압축하거나 적은 빈도의 데이터만 sync에 저장하세요. 큰 데이터는 chrome.storage.local 또는 서버로 옮기세요.
동기화 충돌: 동기화 충돌 시 마지막 쓴 값이 우선될 수 있으므로 충돌 해결 로직(타임스탬프, 버전)을 설계하세요.

마이그레이션: localStorage -> chrome.storage.sync 예제

사용자가 여러 기기에서 동일한 설정을 사용하게 하려면 localStorage에 있던 값을 sync로 마이그레이션하세요. 아래는 안전한 마이그레이션 절차의 예입니다.

앱 실행 시 localStorage에 기존 값이 있는지 확인합니다.
localStorage에 값이 있고 sync에는 아직 없다면 sync로 복사합니다.
복사가 성공하면 localStorage의 원본을 제거하거나 마이그레이션 완료 플래그를 설정합니다.

async function migrateLocalToSync() {
  const localVal = localStorage.getItem('appSettings');
  if (!localVal) return;

  const parsed = JSON.parse(localVal);

  // 이미 sync에 값이 있는지 확인
  const existing = await storageGet('sync', ['appSettings']);
  if (existing && existing.appSettings) {
    console.log('이미 sync에 값이 존재합니다. 마이그레이션 중단.');
    return;
  }

  try {
    await storageSet('sync', { appSettings: parsed });
    // 마이그레이션 완료 플래그
    await storageSet('local', { migratedToSync: true });
    console.log('마이그레이션 완료');
    // 옵션: localStorage.removeItem('appSettings');
  } catch (err) {
    console.error('마이그레이션 오류:', err);
  }
}

migrateLocalToSync();

용량(quota)과 성능 관리(권장 사항)

chrome.storage.sync에는 사용량 제한이 있습니다. (문서에서 최신 제한 값을 확인하세요.)
큰 바이너리 데이터(이미지, 파일 등)는 항상 서버나 파일 스토리지로 옮기세요. sync는 작은 설정/상태 저장에 적합합니다.
쓰기 연산을 배치(batch)하거나 디바운스(debounce)를 적용해 빈번한 동기화를 줄이세요.
변경이 자주 발생하는 값은 local에 두고, 최종 상태만 sync에 업로드하는 패턴을 고려하세요.

테스트 케이스 및 수용 기준(예시)

TC-001 저장 후 읽기: sync.set으로 값을 저장하면 같은 키로 sync.get 시 저장된 값이 반환되어야 함(콜백/프라미스 모두).
TC-002 오프라인 보관: 네트워크가 끊긴 상태에서 set 호출 시 에러가 아닌 로컬 큐에 저장되며, 네트워크 복구 시 동기화되어야 함.
TC-003 권한 누락: storage 권한 없이 API 호출 시 권한 관련 에러가 발생해야 함.
TC-004 대용량 데이터 차단: 지정된 quota를 초과하는 데이터 저장 시 에러를 반환해야 함.
TC-005 충돌 처리: 동시성 변경이 발생했을 때 타임스탬프/버전 규칙에 따라 일관된 결과를 보장해야 함.

수용 기준: 모든 TC가 개발 환경과 실제 Chrome 환경(로그인된 프로필 포함)에서 통과해야 합니다.

역할별 체크리스트

개발자
- manifest에 storage 권한 추가
- 비동기 처리(콜백 또는 프라미스) 적용
- 오류 로깅/복구 루틴 구현
- 데이터 스키마 버전 관리
- 마이그레이션 로직 구현
QA/테스터
- 오프라인/온라인 상태 전환 테스트
- 여러 기기 동기화 테스트(로그인된 동일 계정 사용)
- 권한 없음 상황 테스트
- quota 초과 시 동작 확인
운영자/관리자
- 사용자에게 동기화 활성화 안내
- 개인정보 보관 정책 검토
- 동기화 장애 발생 시 계정 재설정 절차 준비

장애 대응(간단 Runbook)

문제 보고 수집: 영향 범위(사용자 수, 기능), 재현 절차, 로그 첨부.
확인: chrome.runtime.lastError 확인, 네트워크/동기화 상태 점검, 계정 로그인 상태 확인.
임시 조치: 로컬에 저장하도록 우회하거나 fail-safe 모드로 전환.
복구: 동기화 재설정 또는 사용자에게 동기 끄기 후 재로그인 안내.
근본 원인 분석: 코드(권한·데이터 포맷·퀘타 초과), Chrome 버전 이슈, 계정 문제 등.

보안 및 개인정보(간단 가이드)

민감 정보(비밀번호, 신용카드 등)를 chrome.storage에 저장하지 마십시오.
저장해야 할 경우, 반드시 암호화/토큰화하여 저장하고 키 관리는 서버에서 수행하세요.
GDPR/개인정보 관련 규정이 적용되는 데이터는 사용자의 동의와 삭제 요청 프로세스를 준비하세요.

언제 chrome.storage.sync가 적절하지 않은가(반례)

대용량 바이너리를 다루는 경우(이미지, 영상). 이런 데이터는 서버 또는 파일 스토리지로 옮기세요.
즉각적인 강한 일관성(ACID 수준)을 요구하는 데이터. sync는 최종적으로 일관성을 맞추는 모델이므로 실시간 동기 보장이 필요한 경우 서버 중심 설계를 고려하세요.
민감하고 규제 대상인 개인정보: 서버의 안전한 저장소와 규정 준수 메커니즘을 사용하세요.

대안 접근 방식

서버 기반 동기화: 데이터 보안, 버저닝, 충돌 해결을 서버에서 관리합니다.
IndexedDB + 서버 폴백: 로컬에 큰 데이터를 유지하고, 메타데이터만 sync로 동기화.
Firebase/Cloud Sync: 실시간 데이터 동기와 인증을 외부 서비스로 위임.

간단한 모범 사례 체크리스트

저장 항목에 스키마 버전(version)을 추가하세요.
작은 단위로 저장하고 필요 시 병합(merge)하세요.
빈번한 쓰기는 디바운스 처리하세요.
충돌 해결 규칙을 설계하세요(예: 최신 수정시간 우선).
사용량 모니터링 로직을 추가해 quota 초과를 사전에 감지하세요.

의사결정 흐름(간단 Mermaid 다이어그램)

flowchart TD
  A[데이터 저장 필요] --> B{데이터 크기/성격}
  B -->|작고 설정/상태| C[chrome.storage.sync]
  B -->|크거나 바이너리| D[서버/파일 스토리지]
  C --> E{민감정보?}
  E -->|예| D
  E -->|아니오| F[sync로 저장]

(위 다이어그램은 설계 결정의 간단한 힌트입니다.)

호환성 및 마이그레이션 팁

Manifest V2와 V3의 차이를 확인하세요. 확장 환경에서는 Manifest 버전에 따라 일부 API 동작이 다를 수 있습니다.
오래된 확장 사용자에 대한 마이그레이션 경로를 마련하세요(localStorage -> chrome.storage).
크로스-브라우저(예: Edge, Opera)의 chrome.* 호환성을 테스트하세요. 일부 브라우저는 동일한 API를 제공하지만 동작 세부사항이나 동기화 동작이 다를 수 있습니다.

요약 및 권장 행동

chrome.storage.sync는 소규모 설정과 상태를 계정 간 동기화할 때 매우 유용합니다.
항상 권한, 비동기 처리, 용량 제한, 보안 관점에서 설계하세요.
큰 데이터나 민감 데이터는 서버 측으로 옮기고, sync는 최소한의 메타데이터만 사용하세요.

중요: chrome.storage API는 강력하지만 잘못 사용하면 데이터 손실이나 보안 문제가 발생할 수 있습니다. 권한과 사용자 동의를 명확히 하고, 로깅과 오류 처리, 마이그레이션 경로를 준비하세요.

요약(3가지 핵심 포인트):

chrome.storage.sync는 로그인된 Chrome 환경에서 기기 간 데이터를 동기화합니다(동기화 활성화 필요).
비동기 처리, 권한 선언, 용량 관리, 보안 고려가 필수입니다.
큰 데이터와 민감 데이터는 서버 또는 적절한 저장소로 옮기고, sync에는 작은 설정·메타데이터만 사용하세요.