테마나 목록 표시 옵션을 바꿨는데 새로고침하면 기본값으로 돌아간다면, ‘브라우저 캐시 문제’로 묶기 전에 같은 저장 영역을 읽는지, 쓰기가 끝났는지, 저장한 문자열을 현재 코드가 해석할 수 있는지 나눠 보세요. 화면에 적용된 상태와 다음 방문에도 유지될 상태는 다릅니다.
이 글은 테마·간격 같은 작은 표시 설정을 localStorage에 저장하는 웹앱을 다룹니다. 로그인 세션·토큰 보관, 중요한 업무 원본의 유일한 저장소, 기기 간 동기화 구현은 범위 밖입니다. 아래 예제는 이 사이트에서 실행되는 기능이 아니라 가져다 검토할 설명용 코드입니다.
사라진 시점과 실패 지점을 먼저 구분하세요
| 관찰한 현상 | 첫 확인 | 다음 분기 |
|---|---|---|
| 화면은 바뀌지만 새로고침하면 원복 | setItem 실행 여부·예외·같은 키 읽기 | 메모리 반영과 저장 완료 안내 분리 |
| 개발 주소에서는 되고 운영 주소에서는 안 됨 | scheme·host·port와 브라우저 프로필 | 다른 origin의 저장 영역을 혼동했는지 확인 |
| localStorage를 읽는 순간 SecurityError | 저장 정책과 실제 문서 환경 | 객체 접근 자체부터 try/catch 범위에 포함 |
| 쓰기에서 QuotaExceededError | 예외 이름과 해당 origin의 저장 사용 | 거짓 성공 안내·무한 재시도 중단 |
| JSON.parse에서 SyntaxError | 문법에 맞는 문자열인지 | 원문을 자동 삭제하지 않고 읽기 실패로 분류 |
| JSON은 읽혔는데 화면 값이 이상함 | 스키마 버전·필드·타입 | null·배열·”false” 같은 다른 계약을 거절 |
| 다른 탭에서만 설정이 뒤집힘 | 여러 탭의 쓰기 시점과 storage 이벤트 | 충돌 정책과 현재 탭 UI 갱신을 별도로 설계 |
확인 순서는 실패한 키·앱 버전·origin·동작 단계·오류 분류입니다. 저장된 문자열 전체나 토큰을 로그에 덤프할 필요는 없습니다. 사용자 설정을 모두 지우면 문제를 만든 값도 사라지므로 초기화부터 시작하지 마세요.
HTTP·HTTPS와 저장소 접근 실패를 확인하세요
localStorage 문서는 origin별 저장 영역과 정책에 따른 SecurityError를 설명합니다. HTTP와 HTTPS는 서로 다른 저장 영역이며, 같은 호스트라도 포트가 달라지면 origin이 다릅니다. 로컬 파일을 더블클릭해 file:로 여는 환경은 동작이 보장된 배포 환경처럼 취급하지 않습니다.
Web Storage 사용 안내처럼 전역 객체가 존재한다는 검사만으로 쓰기 가능 여부를 보장할 수는 없습니다. 읽기는 되지만 쓰기에서 한도에 걸릴 수 있고 저장 정책도 달라질 수 있으므로 실제 getItem·setItem 각각을 처리해야 합니다. 예제는 window.localStorage를 미리 꺼내 두지 않고 함수 안에서 얻어, 그 접근이 던지는 예외까지 잡습니다.
시크릿 모드·다른 프로필·임베딩·WebView는 별도 조건으로 기록하세요. 저장 용량 문서는 Web Storage와 IndexedDB·Cache API의 정책을 구분합니다. 사용 가능한 디스크가 많다고 localStorage 쓰기가 반드시 성공하는 것은 아니며, 시크릿 세션 종료나 사용자의 사이트 데이터 삭제 뒤에도 설정이 영구 보존된다고 안내해서는 안 됩니다.
없는 값·깨진 JSON·지원하지 않는 값을 분리한 예제
예제 계약은 schema가 숫자 1, theme이 light 또는 dark, compact가 Boolean인 정확히 세 필드입니다. 작은 표시 설정 한 개의 키만 다루며, 계정 정보와 중요 원본은 넣지 않습니다. 읽기는 값을 변경하지 않고 기본값과 실패 분류를 함께 반환합니다. 호출 화면은 분류를 확인해 임시 기본값인지 정상 복원값인지 구분해야 합니다.
function createPreferenceStore(getStorage) {
const key = 'demo:display-prefs:v1';
const defaults = () => ({ schema: 1, theme: 'light', compact: false });
const copy = (v) => ({ schema: 1, theme: v.theme, compact: v.compact });
const valid = (v) => v !== null && typeof v === 'object'
&& !Array.isArray(v) && Object.keys(v).length === 3
&& ['schema', 'theme', 'compact'].every(k => Object.hasOwn(v, k))
&& v.schema === 1 && ['light', 'dark'].includes(v.theme)
&& typeof v.compact === 'boolean';
return {
load() {
let raw;
try {
raw = getStorage().getItem(key);
} catch {
return { state: 'unavailable', value: defaults() };
}
if (raw === null) return { state: 'missing', value: defaults() };
let value;
try {
value = JSON.parse(raw);
} catch {
return { state: 'invalid-json', value: defaults() };
}
if (!valid(value)) {
return { state: 'unsupported-value', value: defaults() };
}
return { state: 'loaded', value: copy(value) };
},
// 사용자가 명시적으로 저장할 때만 호출합니다. 자동 복구용이 아닙니다.
save(value) {
if (!valid(value)) return { state: 'invalid-input' };
try {
getStorage().setItem(key, JSON.stringify(copy(value)));
return { state: 'saved' };
} catch (error) {
return {
state: error?.name === 'QuotaExceededError' ? 'quota' : 'unavailable'
};
}
}
};
}
브라우저에서 사용할 때는 createPreferenceStore(() => window.localStorage)로 연결하고 load 결과의 value를 표시 상태에 반영합니다. missing은 아직 키가 없는 상태이고, unavailable은 읽기에 접근하지 못한 상태입니다. invalid-json은 문법 오류, unsupported-value는 JSON은 읽혔지만 계약이 다른 상태입니다. 이 네 상태를 모두 정상 저장으로 표시하면 안 됩니다.
save는 사용자의 명시적인 저장 동작에만 연결합니다. 읽기 실패 뒤 기본값을 받은 즉시 다시 저장하면 깨진 값이나 미래 버전의 데이터를 덮을 수 있습니다. 예제는 migration·복구·충돌 해결을 구현하지 않습니다. 지원하지 않는 값은 원문을 유지하고, 사용자가 초기화나 교체를 선택하는 제품 정책을 먼저 마련하세요.
setItem은 문자열을 저장하므로 객체를 JSON으로 직렬화합니다. JSON.parse가 성공해도 결과는 null·배열·문자열일 수 있어 필드 검증이 따로 필요합니다. 문자열 “false”를 Boolean false로 임의 변환하지 않고, schema가 2인 값도 지원하지 않는 값으로 남깁니다. 필드를 추가한다면 저장·읽기 계약과 이전 값의 변환 정책을 함께 바꿔야 합니다.
화면 적용과 저장 성공 안내를 나누세요
| 반환 상태 | 화면의 처리 방향 | 피해야 할 안내 |
|---|---|---|
| loaded | 읽은 설정을 적용 | 서버·다른 기기까지 동기화됐다는 설명 |
| missing | 기본값 표시, 필요할 때 명시적으로 저장 | 아직 저장하지 않은 값을 ‘저장 완료’로 표시 |
| invalid-json·unsupported-value | 임시 기본값임을 알리고 복구·교체 정책 적용 | 조용히 기본값으로 덮어쓰기 |
| saved | 이번 쓰기 호출이 예외 없이 끝났음을 안내 | 향후 삭제·브라우저 변경에도 영구 보장 |
| quota·unavailable | 현재 선택을 메모리에 유지할지 결정하고 저장 실패 안내 | 성공 문구·무한 쓰기 재시도·다른 키 일괄 삭제 |
| invalid-input | 입력 계약을 고친 뒤 다시 판단 | 사용자 저장소 용량 탓으로 단정 |
메모리에서 테마를 바꿀 수 있어도 새로고침 뒤 유지된다는 보장은 아닙니다. 저장 실패 시 ‘이번 화면에만 적용되며 저장하지 못했습니다’처럼 의미를 분리하세요. 이 예제는 메모리 상태를 자동 관리하거나 서버로 대체 저장하지 않으며 호출 화면이 그 정책을 소유합니다.
다른 탭의 갱신도 별도 문제입니다. storage 이벤트는 같은 저장 영역을 바꾼 다른 문서에서 발생하며, 변경한 현재 창에는 발생하지 않습니다. 현재 탭 UI를 그 이벤트만 기다리며 갱신하지 마세요. 또 이벤트는 트랜잭션 잠금이 아니므로 여러 탭의 읽기-수정-쓰기를 한 작업처럼 보장하지 않습니다. 이 래퍼는 여러 탭의 동시 쓰기를 해결하지 않습니다.
모의 저장소에서 실제로 확인한 결과
2026년 10월 29일 Node.js v24.19.0에서 위 함수를 그대로 읽어 18개 시나리오를 실행했고 모두 통과했습니다. JSON.parse·stringify는 실제 내장 함수를 사용하고 저장소 객체와 예외는 모의 구현으로 대체했습니다. 실제 브라우저 용량을 채우거나 저장 정책·시크릿 모드·새로고침 보존·여러 탭 이벤트·기기 동작을 시험한 결과는 아닙니다.
| 검사 묶음 | 관찰한 결과 |
|---|---|
| 키 없음, 정상 값과 compact=false | 없는 값과 정상 복원을 나누고 false를 그대로 유지 |
| 문법이 틀린 JSON | invalid-json, 원래 문자열 유지, 자동 쓰기 없음 |
| null·배열·미래 버전·문자열 Boolean·누락·추가 필드 | unsupported-value, 읽기 중 원문 교체 없음 |
| 저장소 getter·getItem 예외 | 함수 밖으로 오류를 던지지 않고 unavailable 반환 |
| 정상 저장과 잘못된 입력 | 정상 값은 모의 저장 왕복, 잘못된 입력은 저장소 접근 전 거절 |
| 용량 예외·접근 거부·기타 쓰기 실패 | saved가 아닌 quota 또는 unavailable, 용량 실패 때 모의 원래 값 유지 |
| 기본값 독립성·무관한 키 | 기본값 객체를 공유하지 않고 다른 키를 지우지 않음 |
표는 여러 검사 조건을 묶어 요약했습니다. 예외를 주입해 실패 분기를 확인한 것이며, 특정 브라우저에서 같은 원인과 메시지가 나왔다는 주장으로 바꾸어 읽으면 안 됩니다.
화면 적용과 새로고침을 비교할 작은 실행 화면
위 함수를 prefs-store.js에 저장합니다. 다음 HTML을 prefs.html, 그다음 JavaScript를 prefs-main.js로 같은 폴더에 두고 전용 로컬 HTTP 서버로 여세요. 두 스크립트는 HTML에 적힌 순서대로 실행됩니다. 저장 함수는 그대로 사용하고, 이 연결 코드는 선택을 미리보기에 적용한 뒤 저장 결과를 따로 안내합니다. 이 사이트의 실제 설정 기능으로 실행되는 코드는 아닙니다.
<!doctype html>
<html lang="ko">
<meta charset="utf-8">
<title>표시 설정 저장 실험</title>
<style>
#preview { padding: 1.5rem; color: #17202a; background: #f2f4f6; }
#preview[data-theme="dark"] { color: #f2f4f6; background: #17202a; }
#preview[data-compact="true"] { padding: .5rem; }
</style>
<label for="theme">테마</label>
<select id="theme"><option value="light">밝게</option><option value="dark">어둡게</option></select>
<label><input id="compact" type="checkbox">촘촘한 간격</label>
<button id="save" type="button">이번 선택으로 저장</button>
<p id="message" role="status"></p>
<div id="preview">설정 미리보기</div>
<script src="prefs-store.js" defer></script>
<script src="prefs-main.js" defer></script>
</html>
const store = createPreferenceStore(() => window.localStorage);
const theme = document.querySelector('#theme');
const compact = document.querySelector('#compact');
const preview = document.querySelector('#preview');
const message = document.querySelector('#message');
function apply(value) {
preview.dataset.theme = value.theme;
preview.dataset.compact = String(value.compact);
}
function announce(state, text) {
message.dataset.state = state;
message.textContent = text;
}
const initial = store.load();
theme.value = initial.value.theme;
compact.checked = initial.value.compact;
apply(initial.value);
const initialMessages = {
loaded: '저장된 설정을 읽었습니다.',
missing: '아직 저장된 설정이 없습니다.',
'invalid-json': '저장값 문법 오류로 기본값을 표시합니다. 저장 버튼을 누르면 기존 값이 교체됩니다.',
'unsupported-value': '지원하지 않는 저장값입니다. 저장 버튼을 누르면 기존 값이 교체됩니다.',
unavailable: '저장소에 접근할 수 없어 기본값을 표시합니다.'
};
announce(initial.state, initialMessages[initial.state]);
document.querySelector('#save').addEventListener('click', () => {
const value = { schema: 1, theme: theme.value, compact: compact.checked };
apply(value);
const result = store.save(value);
const messages = {
saved: '이 브라우저에 저장했습니다.',
quota: '이번 화면에만 적용했습니다. 용량 오류로 저장하지 못했습니다.',
unavailable: '이번 화면에만 적용했습니다. 저장소에 접근하지 못했습니다.',
'invalid-input': '설정 형식이 올바르지 않습니다.'
};
announce(result.state, messages[result.state]);
});
초기 읽기가 실패하면 기본값을 표시하되 저장하지 않습니다. 문법 오류나 지원하지 않는 스키마가 있으면 저장 버튼으로 기존 값을 교체하게 된다는 안내를 먼저 표시합니다. 저장 버튼을 누른 뒤 쓰기가 실패해도 미리보기는 현재 선택을 보여 줍니다. 이때 성공 문구 대신 이번 화면에만 적용됐다고 알립니다.
Chrome에서 복원과 실패 뒤 화면을 비교했습니다
2026년 11월 19일 Chrome 157.0.8103.79 헤드리스의 분리된 브라우저 컨텍스트와 로컬 주소에서 위 세 파일을 실행했습니다. 일반 사용자 프로필이나 운영 사이트의 저장소는 읽거나 변경하지 않았습니다.
| 조건 | 관찰 결과 | 시험 범위 |
|---|---|---|
| 새 저장 영역에서 시작해 어두운 테마·촘촘한 간격 저장 후 새로고침 | 처음에는 missing, 저장 뒤 saved, 새로고침 뒤 loaded였습니다. 선택값과 미리보기가 복원됐습니다. | 실제 localStorage 저장·읽기와 새로고침 |
| 테스트 키에 깨진 JSON 또는 schema=2 준비 | invalid-json과 unsupported-value가 구분됐습니다. 읽은 뒤 원래 문자열은 유지됐습니다. | 합성 테스트 값을 실제 저장소에 넣어 확인 |
| 밝은 테마를 저장한 뒤 setItem에서 용량 예외 주입 | 미리보기는 어두운 테마로 바뀌었지만 quota와 저장 실패 안내가 나왔습니다. 새로고침하면 이전 밝은 테마로 돌아갔습니다. | 예외 주입이며 실제 용량을 채운 시험은 아님 |
| allow-scripts만 허용한 sandbox iframe | 불투명 출처에서 localStorage 접근은 실제 SecurityError였습니다. 읽기·저장은 unavailable이었고 현재 화면의 미리보기는 바뀌었습니다. | 실제 브라우저의 sandbox 제한이며 방문자 저장 정책을 재현한 것은 아님 |
| 별도로 둔 무관한 테스트 키 | 위 조작 뒤에도 유지됐습니다. | 같은 임시 저장 영역의 별도 키 |
이 7개 흐름은 10월 29일의 모의 검사 18건과 별도입니다. 브라우저 종료 뒤 보존·시크릿 모드·여러 탭 충돌·서버 동기화·실제 용량 소진은 시험하지 않았습니다. 이번 왕복이 성공했다는 이유로 이후 삭제나 다른 기기에서도 값이 남는다고 보장하지 않습니다.
브라우저에서 마칠 확인과 복구 범위
- 전용 테스트 origin에서 작은 표시 설정만 사용합니다. 정상 저장 뒤 새로고침해 같은 키·스키마·Boolean 값이 복원되는지 확인합니다.
- 권한이 있는 테스트 프로필에서 읽기·쓰기 실패를 구분하고, 현재 화면 적용과 저장 실패 안내가 함께 맞는지 확인합니다. 일반 사용자 프로필의 저장소를 한도까지 채우지 않습니다.
- 테스트 키에 문법이 틀린 JSON과 미래 스키마 값을 각각 준비해, 읽기만으로 원문이 삭제·교체되지 않는지 확인합니다.
- 브라우저·프로필·HTTP/HTTPS·호스트·포트가 바뀐 경우를 같은 데이터의 소실로 오인하지 않는지 봅니다. 시크릿 세션의 유지 조건은 별도로 확인합니다.
- 여러 탭이 같은 키를 바꾸는 상황과 계정 전환 정책을 검토합니다. 사용자별 설정이면 키 범위와 로그아웃 시 처리 대상을 명시합니다.
- 복구가 필요하면 해당 앱의 해당 키부터 범위를 좁히고, 필요한 원문 보존·변환·사용자 선택을 설계합니다. localStorage.clear나 전체 사이트 데이터 삭제를 기본 해결책으로 삼지 않습니다.
로그에는 키의 종류·스키마 버전·단계·오류 분류만 남겨 먼저 비교하세요. 원문 저장값을 전부 출력하거나 인증 토큰을 수집할 필요는 없습니다. 중요한 원본의 보존 요구가 있다면 브라우저 표시 설정 예제를 그대로 확장하지 말고 별도의 저장·복구 계약을 정해야 합니다.
공식 자료와 이어서 확인할 문제
2026년 10월 29일 아래 공식 원문을 직접 열어 적용 조건을 대조했습니다. 당시 함수 검사는 위 모의 환경 범위로 유지합니다. 2026년 11월 19일에는 localStorage와 setItem 원문을 다시 읽고, 별도의 로컬 브라우저 관찰과 실행 화면을 추가했습니다. 운영 사이트 방문자의 저장소는 읽거나 변경하지 않았습니다.