[{"data":1,"prerenderedAt":21},["ShallowReactive",2],{"$fFdPsilm6pBx24TVb666-jxbmKzWL7J-UirB6bL4UuM8":3},{"uuid":4,"title":5,"summary":6,"content":7,"createdAt":8,"tags":9},"608a597c-9512-4610-9924-65fb5bc09d00","GitHub Pages에 정적 사이트 배포 시 자산(Asset) 경로 깨짐 문제 해결 가이드","GitHub Pages에 정적 웹사이트를 배포할 때, 저장소 이름으로 인해 이미지, CSS, JavaScript 등 자산 경로가 올바르게 로드되지 않는 문제가 자주 발생합니다. 이 문제는 HTML `\u003Cbase>` 태그를 사용하거나, 모든 자산 경로를 상대 경로로 지정하거나, 빌드 도구의 `base` 또는 `publicPath` 옵션을 구성하여 해결할 수 있습니다.","GitHub Pages는 사용자 또는 조직 페이지(예: `username.github.io`)와 달리 프로젝트 페이지(예: `username.github.io\u002F[YOUR_REPOSITORY_NAME]\u002F`)의 경우 저장소 이름을 포함하는 서브 경로에서 사이트를 호스팅합니다. 이때 웹사이트 내의 이미지, CSS, JavaScript 파일 등의 자산(Asset) 경로가 절대 경로(예: `\u002Fassets\u002Fimage.png`)로 지정되어 있으면, 브라우저는 이를 `username.github.io\u002Fassets\u002Fimage.png`에서 찾으려 시도하여 `404 Not Found` 오류를 발생시키고 결국 페이지가 깨져 보이게 됩니다. 이 가이드는 Next.js와 같은 특정 프레임워크의 `basePath` 설정이 아닌, 일반적인 정적 HTML\u002FCSS\u002FJavaScript 사이트 또는 범용 빌드 도구(Vite, Webpack 등)를 사용하는 프로젝트에서 이 문제를 해결하는 방법을 제시합니다.\n\n## 문제의 원인: GitHub Pages의 URL 구조\n\nGitHub Pages는 두 가지 유형의 URL로 사이트를 제공합니다.\n\n1.  **사용자\u002F조직 페이지**: `https:\u002F\u002Fusername.github.io` 또는 `https:\u002F\u002Forgname.github.io`\n2.  **프로젝트 페이지**: `https:\u002F\u002Fusername.github.io\u002F[YOUR_REPOSITORY_NAME]\u002F` 또는 `https:\u002F\u002Forgname.github.io\u002F[YOUR_REPOSITORY_NAME]\u002F`\n\n대부분의 경우 프로젝트 페이지로 배포하게 되는데, 이때 `[YOUR_REPOSITORY_NAME]` 부분이 URL의 서브 경로로 포함됩니다. 만약 HTML, CSS, JavaScript 파일 내에서 자산 경로를 `\u002Fcss\u002Fstyle.css`나 `\u002Fimages\u002Flogo.png`와 같이 루트를 기준으로 하는 절대 경로로 지정하면, 브라우저는 이를 `https:\u002F\u002Fusername.github.io\u002Fcss\u002Fstyle.css`에서 찾으려고 합니다. 하지만 실제 파일은 `https:\u002F\u002Fusername.github.io\u002F[YOUR_REPOSITORY_NAME]\u002Fcss\u002Fstyle.css`에 있으므로 경로를 찾지 못하게 됩니다.\n\n## 해결 방법 1: HTML `\u003Cbase>` 태그 사용\n\nHTML `\u003Cbase>` 태그는 문서 내의 모든 상대 URL에 대한 기준 URL을 지정합니다. `\u003Chead>` 태그 안에 이 태그를 추가하여 GitHub Pages 저장소 이름을 기준으로 설정하면, 모든 상대 경로가 올바르게 해석됩니다.\n\n```html\n\u003C!DOCTYPE html>\n\u003Chtml lang=\"ko\">\n\u003Chead>\n    \u003Cmeta charset=\"UTF-8\">\n    \u003Cmeta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n    \u003Ctitle>내 정적 사이트\u003C\u002Ftitle>\n    \u003C!-- GitHub Pages 저장소 이름을 기준으로 \u003Cbase> href 설정 -->\n    \u003C!-- 예: 저장소 이름이 'my-blog'라면 href=\"\u002Fmy-blog\u002F\" -->\n    \u003Cbase href=\"\u002F[YOUR_REPOSITORY_NAME]\u002F\"> \n    \u003Clink rel=\"stylesheet\" href=\"css\u002Fstyle.css\">\n\u003C\u002Fhead>\n\u003Cbody>\n    \u003Ch1>환영합니다!\u003C\u002Fh1>\n    \u003Cimg src=\"images\u002Flogo.png\" alt=\"로고\">\n    \u003Cp>이것은 정적 사이트입니다.\u003C\u002Fp>\n    \u003Cscript src=\"js\u002Fmain.js\">\u003C\u002Fscript>\n\u003C\u002Fbody>\n\u003C\u002Fhtml>\n```\n\n**장점**: 한 번의 설정으로 모든 상대 경로에 적용됩니다. 내부 링크(예: `\u003Ca href=\"about.html\">`)에도 영향을 미쳐 `\u002F[YOUR_REPOSITORY_NAME]\u002Fabout.html`로 연결됩니다.\n**주의사항**: SPA(Single Page Application)나 클라이언트 측 라우팅을 사용하는 복잡한 사이트에서는 `\u003Cbase>` 태그가 예상치 못한 동작을 유발할 수 있으므로 주의해야 합니다. 일반적인 정적 사이트에는 유용합니다.\n\n## 해결 방법 2: 모든 자산 경로를 상대 경로로 지정\n\n가장 확실하고 안전한 방법은 모든 자산 경로를 현재 HTML 파일 또는 CSS 파일의 위치를 기준으로 하는 상대 경로로 지정하는 것입니다. 이는 `\u003Cbase>` 태그의 영향을 받지 않고, 빌드 도구 설정 없이도 작동합니다.\n\n**HTML 파일 (`index.html`)**\n\n```html\n\u003C!DOCTYPE html>\n\u003Chtml lang=\"ko\">\n\u003Chead>\n    \u003Cmeta charset=\"UTF-8\">\n    \u003Cmeta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n    \u003Ctitle>내 정적 사이트\u003C\u002Ftitle>\n    \u003C!-- CSS 파일은 현재 HTML 파일 기준 상대 경로 -->\n    \u003Clink rel=\"stylesheet\" href=\".\u002Fcss\u002Fstyle.css\">\n\u003C\u002Fhead>\n\u003Cbody>\n    \u003Ch1>환영합니다!\u003C\u002Fh1>\n    \u003C!-- 이미지 파일은 현재 HTML 파일 기준 상대 경로 -->\n    \u003Cimg src=\".\u002Fimages\u002Flogo.png\" alt=\"로고\">\n    \u003Cp>이것은 정적 사이트입니다.\u003C\u002Fp>\n    \u003C!-- JS 파일도 현재 HTML 파일 기준 상대 경로 -->\n    \u003Cscript src=\".\u002Fjs\u002Fmain.js\">\u003C\u002Fscript>\n\u003C\u002Fbody>\n\u003C\u002Fhtml>\n```\n\n**CSS 파일 (`css\u002Fstyle.css`)**\n\n```css\n\u002F* background-image도 CSS 파일 기준 상대 경로 *\u002F\nbody {\n    background-image: url('..\u002Fimages\u002Fbackground.png'); \u002F* css 폴더에서 상위로 이동 후 images 폴더 *\u002F\n    font-family: Arial, sans-serif;\n}\n\nh1 {\n    color: #333;\n}\n```\n\n**장점**: 가장 견고하며, 어떤 환경에서도 경로 문제가 발생할 가능성이 낮습니다. 빌드 도구 설정이 필요 없습니다.\n**주의사항**: 파일 구조가 복잡해지면 경로를 일일이 관리하기 번거로울 수 있습니다.\n\n## 해결 방법 3: 빌드 도구의 `base` 또는 `publicPath` 옵션 활용\n\nVite, Webpack, Parcel 등 모듈 번들러나 빌드 도구를 사용하여 정적 사이트를 생성하는 경우, 해당 도구의 설정에서 `base` 또는 `publicPath` 옵션을 지정하여 모든 자산 경로에 저장소 이름을 자동으로 붙일 수 있습니다. 이는 빌드 시점에 경로를 수정해주므로, 수동으로 경로를 변경할 필요가 없습니다.\n\n**Vite 프로젝트 예시 (`vite.config.ts`)**\n\n```ts\nimport { defineConfig } from 'vite';\n\nexport default defineConfig({\n  \u002F\u002F GitHub Pages에 배포할 저장소 이름을 base 경로로 설정\n  \u002F\u002F 예: https:\u002F\u002Fusername.github.io\u002Fmy-blog\u002F 일 경우 '\u002Fmy-blog\u002F'\n  base: '\u002F[YOUR_REPOSITORY_NAME]\u002F', \n  build: {\n    outDir: 'dist', \u002F\u002F 빌드 결과물이 저장될 디렉토리\n  },\n});\n```\n\n**Webpack 프로젝트 예시 (`webpack.config.js`)**\n\n```javascript\nconst path = require('path');\n\nmodule.exports = {\n  \u002F\u002F ... (다른 설정)\n  output: {\n    path: path.resolve(__dirname, 'dist'),\n    filename: 'bundle.js',\n    \u002F\u002F GitHub Pages에 배포할 저장소 이름을 publicPath로 설정\n    \u002F\u002F 예: https:\u002F\u002Fusername.github.io\u002Fmy-blog\u002F 일 경우 '\u002Fmy-blog\u002F'\n    publicPath: '\u002F[YOUR_REPOSITORY_NAME]\u002F', \n  },\n  \u002F\u002F ... (다른 설정)\n};\n```\n\n**장점**: 빌드 도구가 자동으로 모든 자산 경로를 처리하므로 개발자가 직접 경로를 수정할 필요가 없습니다. 대규모 프로젝트에 적합합니다.\n**주의사항**: 사용하는 빌드 도구에 따라 설정 방법이 다르므로, 해당 도구의 공식 문서를 참고하여 정확한 옵션과 값을 확인해야 합니다.\n\n## 흔히 하는 실수 및 주의사항\n\n*   **로컬 환경과의 차이**: 로컬에서 `index.html`을 직접 열거나 `http-server` 등으로 서빙할 때는 `\u002F[YOUR_REPOSITORY_NAME]\u002F`와 같은 서브 경로가 없으므로 경로 문제가 발생하지 않을 수 있습니다. 반드시 배포된 GitHub Pages URL에서 최종 확인해야 합니다.\n*   **잘못된 `[YOUR_REPOSITORY_NAME]`**: 저장소 이름을 정확히 입력해야 합니다. 대소문자를 구분하며, 오타가 있으면 경로가 깨집니다.\n*   **`base` 태그와 내부 링크**: `\u003Cbase>` 태그는 페이지 내의 모든 상대 URL에 영향을 미치므로, 내부 페이지 링크(`\u003Ca>`)가 예상과 다르게 동작할 수 있습니다. 예를 들어 `\u003Ca href=\"posts\u002F1.html\">`은 `\u002F[YOUR_REPOSITORY_NAME]\u002Fposts\u002F1.html`로 연결됩니다.\n*   **환경 변수 활용**: 만약 여러 환경(개발, 프로덕션, GitHub Pages)에 따라 `base` 경로가 달라져야 한다면, 환경 변수를 활용하여 빌드 시점에 동적으로 경로를 설정하는 방법을 고려해볼 수 있습니다. 이는 프로젝트의 복잡성에 따라 달라질 수 있으니 확인이 필요합니다.","2026-08-24T14:01:43.316+09:00",[10,11,12,13,14,15,16,17,18,19,20],"Asset Path","CSS","GitHub Pages","HTML","JavaScript","Vite","Webpack","경로 문제","기술 가이드","자산 경로","정적 사이트",1788152656741]