콘텐츠로 건너뛰기
DevLab

📱 Web App Manifest 생성기

PWA 용 manifest.json 을 폼으로 작성. name / start_url / display / theme_color, 다중 크기 icons 표, shortcuts, share_target, protocol_handlers 지원. HTML link 태그도 함께 출력.

완전 무료 가입 불필요 브라우저 완결 5 개 언어 다크 모드

🔒 개인정보 보호

기본 정보

아이콘 (크기와 src)

체크된 크기가 icons 배열에 포함됩니다.

앱 바로가기 (최대 4)


    
    






    
📖 자주 걸리는 지점


        
PWA 에 필요한 manifest.json 을 폼으로 작성합니다. name / start_url / display / theme_color 에 더해 여러 크기의 icons, shortcuts, share_target, protocol_handlers 까지 지원하고 HTML 의 link 태그도 함께 출력합니다. 처리는 브라우저 안에서 끝납니다. 다만 manifest 만으로는 앱을 설치할 수 없습니다 — 설치 가능으로 판정되려면 HTTPS·서비스 워커·필수 필드·규정 크기의 아이콘이 갖춰져야 합니다. 「manifest 를 두었는데 설치 버튼이 안 나온다」의 원인은 대개 manifest 바깥에 있습니다.

    
        

        

            
                

                    사례
                    무슨 일이 일어나는가
                    어떻게 하면 되는가
                

            
            
                                

                    설치 가능 조건은 manifest 단독으로 만족되지 않는다
                    브라우저가 설치를 제안하려면 여러 조건을 모두 만족해야 합니다: HTTPS (또는 localhost), fetch 이벤트를 가진 서비스 워커가 등록되어 있을 것, name 또는 short_name, start_url, display 가 standalone / fullscreen / minimal-ui 중 하나, 그리고 192px 와 512px 아이콘. 하나라도 빠지면 오류 없이 그저 버튼이 나타나지 않습니다 — 무엇이 모자란지 알려 주지 않는 것이 최대의 난관입니다. 나아가 iOS 의 Safari 는 manifest 의 상당 부분을 무시합니다 — 홈 화면에 추가할 때의 아이콘은 apple-touch-icon 에서 가져오고 표시 모드는 apple-mobile-web-app-capable 로 정해집니다.
                    추측하지 말고 Chrome DevTools 의 Application > Manifest 를 여세요. 만족하지 못한 조건이 구체적인 문장으로 열거됩니다 — 이 화면을 보느냐 마느냐로 해결까지의 시간이 몇 시간 달라집니다. Lighthouse 의 PWA 감사도 같은 판정을 기계적으로 실행합니다. 서비스 워커는 「등록되어 있다」는 것만으로는 부족합니다 — fetch 이벤트 핸들러가 실제로 존재해야 하므로 빈 sw.js 로는 조건을 만족하지 않습니다. iOS 도 대상으로 한다면 manifest 와는 별도로 apple-touch-icon (180×180) 과 apple-mobile-web-app-title 을 HTML 에 더하세요 — manifest 만 정비해도 iOS 에서는 반영되지 않습니다.
                

                                

                    start_url 과 scope 의 상대 해석
                    이 둘은 사이트의 루트가 아니라 manifest 파일의 위치를 기준으로 해석됩니다. /static/manifest.json 에 둔 manifest 에서 "start_url": "index.html" 이라고 쓰면 기동 URL 은 /static/index.html 이 됩니다 — 존재하지 않으면 설치는 되었는데 열면 404 인 상태가 됩니다. scope 는 영향이 더 넓어서 앱 창 안에 머무는 URL 의 범위를 정합니다 — 범위 밖으로 가는 링크를 밟으면 브라우저로 튀어나갑니다. scope 를 쓰지 않은 경우의 기본값도 manifest 의 위치이므로 /static/ 에 둔 채 아무것도 쓰지 않으면 사이트 본체가 전부 범위 밖이 됩니다. 그리고 start_url 이 scope 밖에 있으면 애초에 설치 가능으로 판정되지 않습니다.
                    둘 다 앞에 슬래시를 붙인 절대 경로로 쓰세요 — "start_url": "/", "scope": "/". 이것만으로 상대 해석 문제는 전부 사라집니다. 사이트의 일부만 PWA 로 하는 경우에는 "scope": "/app/" 처럼 범위를 명시하고 그 범위 안에 start_url 이 들어 있는지 확인하세요. start_url 에 쿼리를 붙이면 애널리틱스에서 PWA 경유 기동을 구별할 수 있습니다 — "/?source=pwa" 처럼. manifest 자체는 어디에 두어도 상관없지만 <link rel="manifest"> 의 href 와 실제 경로를 일치시키세요 — manifest 가 404 를 돌려주어도 브라우저는 조용히 무시할 뿐 아무것도 표시하지 않습니다.
                

                                

                    아이콘이 Android 에서 잘린다 (maskable)
                    Android 의 런처는 아이콘을 원형이나 둥근 사각형으로 마스킹합니다. 따라서 "purpose": "any" 아이콘만 준비하면 네 모서리가 잘려 나갑니다 — 로고가 사각 틀 가득히 그려져 있으면 가장자리의 글자가 사라집니다. 이것을 피하기 위한 지정이 "purpose": "maskable" 이며 마스크용 아이콘은 중앙 40% 정도를 안전 영역으로 삼고 그 바깥은 잘린다는 전제로 디자인합니다. 그런데 maskable 만 준비하는 것도 잘못입니다 — 마스킹하지 않는 환경 (데스크톱 작업 표시줄이나 스플래시 화면) 에서는 여백이 큰 작은 로고로 표시됩니다. 어느 한쪽만으로는 반드시 어딘가에서 깨진다는 것이 이 사양의 요점입니다.
                    두 종류를 별개의 엔트리로 모두 등록하세요. 같은 512×512 라도 틀 가득한 것을 "purpose": "any", 여백을 둔 것을 "purpose": "maskable" 로 나란히 씁니다 — 하나의 엔트리에 "any maskable" 이라고 쓰는 방법도 있지만 그 경우에는 양쪽 요건을 동시에 만족하는 도안이어야 합니다. 확인은 Chrome DevTools 의 Application > Manifest 에서 할 수 있습니다 — 마스크를 씌운 상태의 미리보기가 표시되므로 잘리는 정도를 그 자리에서 볼 수 있습니다. 크기는 192 와 512 두 가지를 최소한 준비하고 SVG 가 아니라 PNG 로 하세요 — SVG 지원은 환경에 따라 들쭉날쭉합니다.
                

                            
        

    

    
        
manifest 는 캐시됩니다. 변경해도 이미 설치된 단말에는 바로 반영되지 않습니다 — 아이콘이나 이름을 바꿨는데 예전 그대로인 것은 대개 이것입니다. 반영 타이밍은 브라우저에 달려 있으므로 개발 중에는 DevTools 의 Application > Manifest 에서 갱신을 유도하고 제거와 재설치로 확인하세요. 그리고 manifest.json 은 Content-Type: application/manifest+json 으로 배포하세요 — 서버가 text/plain 으로 돌려주면 읽히지 않는 경우가 있습니다. 설계 면에서 하나: display: "standalone" 은 브라우저의 UI 를 없애므로 뒤로 가기 버튼도 URL 바도 사라집니다 — 앱 안에 돌아갈 수단을 마련해 두지 않으면 사용자가 막다른 길에 들어갑니다. 외부 사이트로의 링크는 scope 밖이라 브라우저로 튀지만 거기서 돌아올 수 있다는 보장은 없습니다. 마지막으로 PWA 로 만들었다고 해서 설치되는 것은 아닙니다 — 설치를 유도하는 동선과 그에 걸맞은 이점 (오프라인 동작·알림·기동 속도) 을 사용자에게 보여 줄 수 있는가가 본체입니다.

    









    
📖 사용법

    
    
                
  1. 
            1
            
    
                
    기본 정보 입력
    
                
    name, short_name, start_url 등 입력.
    
            
    
        
    2. 
                
  2. 
            2
            
    
                
    아이콘과 바로가기 설정
    
                
    사용할 크기 체크, 접두사와 확장자 지정. 바로가기 최대 4 개 추가.
    
            
    
        
    3. 
                
  3. 
            3
            
    
                
    생성 후 배포
    
                
    JSON 생성을 누르고 manifest.json 저장, HTML 스니펫을 head 에 붙여넣기.
    
            
    
        
    4. 
            






    
❓ 자주 묻는 질문

    

                

            
                PWA 인식을 위한 최소 요건은?
                
            
            
name, start_url, display, 192x192 + 512x512 아이콘, HTTPS, 서비스 워커 필요.

        

                

            
                maskable 아이콘이 필요합니까?
                
            
            
Android 적응형 아이콘에 강력 권장. 중앙 80% 안에 주요 디자인 배치.

        

                

            
                manifest 변경이 반영되지 않습니다
                
            
            
브라우저 캐시가 강합니다. 짧은 Cache-Control 또는 쿼리 문자열 사용.

        

            






    

        
🔗 관련 도구

        
    






    

        
            🐛 이 도구에서 문제가 발생했나요?
            
        

        

            무료 · 가입 불필요. 재현 절차만이라도 도움이 됩니다. 보고는 운영자에게 직접 전달되어 개선에 사용됩니다.
        


        

                        

            

                
                
            


            

                
                
                

                    ※ 재현을 위해 브라우저 정보 (UA / 화면 / 언어 / URL) 가 자동 전송됩니다