TWA 앱, 고쳤는데 왜 그대로일까? 캐시와의 전쟁에서 배운 것
TWA 앱에서 고친 화면이 휴대폰에 바로 반영되지 않는 일은 서비스 워커의 저장 규칙이나 브라우저 캐시 때문인 경우가 많습니다. 캐시를 없애기보다 갱신 규칙을 정하는 법, 주소창이 남을 때 확인할 소유 확인, 카카오톡과 삼성 인터넷에서 달라지는 점까지 정리했습니다.

TWA 앱에서 분명히 고쳤는데 휴대폰에서는 왜 옛 화면이 나올까요? 서비스 워커에 "저장된 파일 먼저" 규칙이 들어 있거나, 브라우저가 파일을 오래 저장하도록 설정된 경우가 많습니다. 캐시를 없애기보다 무엇을 저장하고 언제 새것으로 바꿀지 처음부터 정해 두는 것이 답이었습니다. 여기에 주소창이 남을 때의 소유 확인, 카카오톡과 삼성 인터넷에서 달라지는 점까지 알아 두면 TWA 앱을 낼 때 덜 막힙니다.

예전에 바이브 코딩은 웹앱으로 시작하고, TWA로 앱까지 만들어 보라는 글을 썼습니다. TWA는 내 웹앱을 주소창 없이 안드로이드 앱처럼 여는 방법입니다. 웹에서 바꾼 내용을 앱에서도 보여 줄 수 있다는 게 큰 장점이고요.
그런데 실제로 만들어 보니, 그 "바로 반영"이 생각처럼 되지 않을 때가 있었습니다. 분명히 고쳤는데 휴대폰에서는 계속 옛 화면이 나왔습니다. 저도 이것 때문에 한참 헤맸습니다. 거의 캐시와의 전쟁이었죠. 오늘은 그 싸움에서 배운 것을 정리해 보겠습니다.
고쳤는데 왜 안 바뀔까요?
캐시는 한 번 받은 파일을 저장해 두었다가 다시 쓰는 것입니다. 같은 파일을 매번 내려받지 않으니 화면이 빨리 열립니다. 문제는 새 파일을 확인해야 할 때도 저장된 옛 파일을 쓰는 경우입니다.
저처럼 고친 화면이 안 보인다면, 먼저 두 가지를 구분해서 보면 좋습니다.
첫째는 서비스 워커의 저장 규칙입니다. 서비스 워커는 웹앱과 서버 사이에서 파일 요청을 처리할 수 있는 프로그램입니다. 이것을 사용하면서 "저장된 파일 먼저"라는 규칙을 넣어 두었다면, 서버에 새 파일이 있어도 옛 화면을 보여 줄 수 있습니다. 새 서비스 워커를 받아 놓고도 기존 화면이 닫히기를 기다리는 경우도 있고요.
둘째는 브라우저의 캐시입니다. 브라우저도 파일을 따로 저장합니다. 같은 이름의 파일을 언제 다시 확인할지는 서버가 보낸 캐시 설정 등에 따라 달라집니다. 파일 이름이 같다고 무조건 옛 파일을 쓰는 것은 아니지만, 오래 저장하도록 설정해 두었다면 수정 반영이 늦어질 수 있습니다.
TWA는 실행을 맡은 브라우저와 저장 공간을 공유합니다. 그래서 앱만 지웠다 다시 설치했다고 웹사이트의 저장 데이터까지 모두 초기화됐다고 생각하면 안 됩니다. 어느 브라우저로 열렸는지도 함께 확인해야 합니다.
또 하나 구분할 것이 있습니다. 설치된 안드로이드 앱의 이름·아이콘·시작 화면처럼 앱 파일에 포함된 정보는 웹 화면과 다릅니다. 이런 정보는 캐시를 지우는 문제가 아니라, 앱을 다시 만들어 업데이트해야 하는 경우입니다.
캐시를 없애기보다, 갱신 규칙을 정합니다
한동안은 캐시를 전부 없애면 편하겠다고 생각했습니다. 하지만 그러면 빨리 열리는 장점도 함께 줄어듭니다. 중요한 것은 무엇을 저장하고, 언제 새것으로 바꿀지 정하는 일이었습니다.
처음부터 챙겨 두면 좋은 것은 다음 다섯 가지입니다.
- 화면은 최신 내용을 확인하도록 합니다. 온라인에서는 서버의 새 내용을 우선 확인하고, 오프라인 화면이 필요하다면 그때 사용할 저장본을 따로 정합니다.
- 바뀐 파일은 구분되게 만듭니다. 그림이나 코드 파일의 내용이 바뀌면 파일 이름에 버전이나 고유한 값을 붙여, 이전 파일과 구분합니다.
- 서비스 워커의 업데이트도 확인합니다. 파일을 새로 받았는지뿐 아니라, 새 버전이 실제로 적용됐는지까지 봅니다.
- 새 버전 안내를 넣습니다. 작업 중인 내용을 잃지 않도록 "새 버전이 있습니다. 새로고침할까요?"처럼 사용자가 바꿀 시점을 알게 합니다.
- 화면에 버전 번호를 표시합니다. "안 바뀌었어요"라는 말을 들었을 때 서로 같은 버전을 보고 있는지 바로 확인할 수 있습니다.

내용이 바뀌지 않는 파일은 오래 저장하고, 바뀐 파일에는 새로운 이름을 주는 방식이 공식 자료에서도 안내됩니다. 무조건 저장하지 않는 것보다 파일의 역할에 맞게 정하는 것입니다.
AI와 만든다면 이렇게 요청해 보세요.
이 웹앱은 TWA 앱으로도 사용할 거야. 화면, 그림과 코드 파일, 서비스 워커의 갱신 규칙을 구분해서 설명해 줘. 새 버전 안내와 현재 버전 표시도 넣고 싶어. 바로 수정하지 말고, 지금 구조에서 업데이트가 늦어질 수 있는 곳부터 확인해 줘.
다만 캐시만 원인은 아닙니다. 서버에 새 버전이 제대로 올라갔는지, 중간에서 파일을 전달하는 서비스가 옛 파일을 보내는지도 확인해야 합니다. 고친 코드와 실제 배포된 코드가 같은지부터 보는 것이 순서였습니다.
주소창이 남으면, 전체 화면보다 소유 확인부터
TWA 앱을 열었는데 위에 주소창이 보인다면, 먼저 웹사이트와 앱의 소유 관계 확인을 살펴보세요. 확인에 실패하면 주소창이 있는 브라우저 화면으로 열릴 수 있습니다.
웹사이트의 .well-known/assetlinks.json 파일에는 앱 정보와 서명 인증서 정보가 들어갑니다. 특히 내 컴퓨터에서 설치한 앱은 되는데 플레이스토어에서 받은 앱은 안 된다면, Play Console의 앱 서명 인증서 지문이 맞는지 확인해야 합니다. 업로드할 때 쓰는 키와 실제 배포 앱의 서명 키가 다를 수 있기 때문입니다.
주소창을 숨기는 것과 휴대폰 위아래의 시스템 표시 영역을 숨기는 것도 별개입니다. 소유 확인이 된 뒤, 게임처럼 화면을 넓게 써야 한다면 전체 화면 설정을 추가로 확인하면 됩니다. 단순히 "전체 화면으로 바꿔 줘"라고만 해서는 소유 확인 문제까지 해결되지 않습니다.
카카오톡에서 연 화면과 브라우저에서 연 화면은 다릅니다
링크를 카카오톡으로 보내면 받은 분은 대개 카카오톡 안에서 엽니다. 같은 웹페이지라도 크롬이나 삼성 인터넷에서 열었을 때와 설치·로그인 동작이 다를 수 있습니다.
특히 구글 로그인이 필요한 화면은 주의해야 합니다. 구글은 보안 정책상 내장 웹뷰를 통한 로그인을 제한합니다. 따라서 카카오톡 안에서 로그인이 막히면, 외부 브라우저로 열어 다시 확인하는 편이 좋습니다.
그래서 링크를 보낼 때는 이런 안내를 함께 적습니다.
로그인이나 설치가 잘 안 되면, 화면의 메뉴에서 '다른 브라우저로 열기'에 해당하는 항목을 선택해 주세요.
메뉴 이름과 위치는 휴대폰이나 앱 버전에 따라 다를 수 있으니, 특정 위치를 무조건 누르라고 안내하기보다는 실제 화면을 보고 알려 주는 것이 낫습니다.
크롬에서 됐다고 확인이 끝난 것은 아닙니다
TWA는 설치된 브라우저를 이용합니다. 일반적인 구성에서는 TWA를 지원하는 기본 브라우저가 우선 선택됩니다. 그래서 갤럭시폰의 기본 브라우저가 삼성 인터넷이라면, 크롬에서 확인한 것과 다른 환경에서 앱이 실행될 수 있습니다.
브라우저가 달라지면 로그인 상태나 저장된 파일도 달라질 수 있습니다. 저는 앱을 내기 전에 다음 내용을 함께 확인해 보길 권합니다.
- 크롬과 삼성 인터넷에서 각각 열리는지
- 새 버전을 올린 뒤 기존에 쓰던 휴대폰에서도 바뀌는지
- 다크 모드와 큰 글씨에서도 버튼이나 글자가 잘 보이는지
- 카카오톡으로 받은 링크에서 로그인과 설치까지 이어지는지
처음 설치했을 때 잘 뜨는 것만으로는 부족했습니다. 이미 쓰던 사람이 업데이트된 화면을 제대로 받는지도 확인해야 했습니다.

TWA는 여전히 웹앱 하나로 앱까지 만들 수 있는 좋은 방법이라고 생각합니다. 다만 "웹만 고치면 끝"이 되려면, 처음 만들 때부터 새 버전이 사용자에게 어떻게 전달될지까지 정해 두어야 하더라고요.
정리
- 고친 화면이 안 바뀌면 서비스 워커의 저장 규칙과 브라우저 캐시를 나눠서 봅니다. 앱 이름·아이콘·시작 화면은 앱 업데이트가 필요합니다.
- 캐시를 없애기보다, 화면은 최신 내용을 확인하고 바뀐 파일은 이름으로 구분하는 갱신 규칙을 정합니다.
- 새 버전 안내와 버전 번호 표시는 처음부터 넣어 두면 좋습니다.
- 주소창이 남으면 assetlinks.json과 Play Console의 앱 서명 인증서 지문부터 확인합니다.
- 카카오톡 안에서는 로그인·설치가 다를 수 있고, 갤럭시폰에서는 삼성 인터넷으로 열릴 수 있으니 함께 확인합니다.
원팩에서 만드는 업무 시스템 FROX도 웹을 중심으로 PC와 휴대폰에서 함께 쓰도록 만들기 때문에, 새 버전이 모든 화면에 제대로 전달되는지 확인하는 일을 늘 챙기고 있습니다.
함께 읽으면 좋은 글: 바이브 코딩, 웹앱 하나로 시작하세요: TWA로 플레이스토어 앱까지 · 웹앱 배포하고 휴대폰 홈 화면에 추가하기 (나만의 스케줄러 만들기 7편)
출처

프로그램 기획자로 일하다, 2년 동안 하루 5~12시간씩 AI와 일하며 개발자가 됐습니다. 지금은 원팩에서 AI가 결합된 업무 시스템 FROX를 만듭니다.
