[{"data":1,"prerenderedAt":18},["ShallowReactive",2],{"$fhnU6ao6od58vlfcrMisR0CDPulI7wIp_L26xvfO5q7I":3},{"uuid":4,"title":5,"summary":6,"content":7,"createdAt":8,"tags":9},"b030bfa4-fef2-4c58-947e-90f622fd3ee6","GitHub Pages에 Nuxt.js 정적 사이트 배포 시 자산 경로 깨짐 문제 해결하기","GitHub Pages에 Nuxt.js로 개발된 정적 사이트를 배포할 때, 이미지, CSS, JavaScript 등 자산 경로가 올바르게 로드되지 않는 문제는 저장소 이름으로 인한 서브 경로 문제 때문입니다. 이 문제는 `nuxt.config.ts` 파일에서 `app.baseURL` 설정을 조정하여 해결할 수 있습니다.","GitHub Pages에 Nuxt.js로 개발된 정적 사이트를 배포할 때, 자산(Asset) 경로가 깨지는 문제는 흔히 발생하는 문제입니다. 이는 주로 GitHub Pages가 저장소 이름을 포함하는 서브 경로(예: `username.github.io\u002Frepository-name\u002F`)로 사이트를 제공하기 때문에 발생합니다. Nuxt.js 프로젝트의 `nuxt.config.ts` 파일에서 `app.baseURL` 설정을 올바르게 지정함으로써 이 문제를 해결할 수 있습니다.\n\n## 원인: GitHub Pages의 서브 경로 문제\n\nGitHub Pages는 크게 두 가지 방식으로 웹사이트를 호스팅합니다.\n\n1.  **사용자\u002F조직 페이지**: `username.github.io` 또는 `organization.github.io`와 같이 루트 도메인에서 직접 호스팅됩니다.\n2.  **프로젝트 페이지**: `username.github.io\u002Frepository-name\u002F`과 같이 저장소 이름을 포함하는 서브 경로에서 호스팅됩니다.\n\nNuxt.js와 같은 정적 사이트 생성기는 기본적으로 자산 경로를 웹사이트의 루트(` \u002F `)를 기준으로 생성합니다. 예를 들어, `assets\u002Fimage.png`는 `\u002Fassets\u002Fimage.png`로 빌드됩니다. 사용자\u002F조직 페이지에서는 이 경로가 올바르게 작동하지만, 프로젝트 페이지에서는 실제 경로가 `\u002Frepository-name\u002Fassets\u002Fimage.png`여야 합니다. `repository-name`이 누락되면서 브라우저는 자산을 찾지 못해 \"404 Not Found\" 오류를 발생시키고, 결과적으로 사이트의 스타일이나 기능이 깨지게 됩니다.\n\n## Nuxt.js에서 자산 경로 설정하기\n\nNuxt.js 3에서는 `nuxt.config.ts` 파일의 `app.baseURL` 옵션을 사용하여 모든 자산(이미지, CSS, JavaScript 등) 및 클라이언트 측 라우팅의 기본 경로를 지정할 수 있습니다. 이 값을 GitHub 저장소 이름과 동일하게 설정하면 GitHub Pages의 서브 경로 문제를 해결할 수 있습니다.\n\n`app.baseURL`은 Nuxt 애플리케이션의 모든 상대 경로(자산, 라우팅)에 적용되는 기본 URL을 정의합니다. `ssr: false`와 함께 사용하면 정적 사이트 배포 시 경로 문제가 효과적으로 해결됩니다.\n\n### `nuxt.config.ts` 수정 예시\n\n아래 예시에서는 `d-korea-law`라는 저장소 이름을 사용합니다. 실제 프로젝트에서는 `'\u002Fd-korea-law\u002F'` 부분을 본인의 GitHub 저장소 이름으로 변경해야 합니다.\n\n```typescript\n\u002F\u002F nuxt.config.ts\nimport { defineNuxtConfig } from 'nuxt'\n\n\u002F\u002F 배포 환경에 따라 baseURL을 다르게 설정합니다.\n\u002F\u002F NODE_ENV가 'production'일 경우 GitHub Pages 저장소 이름을 사용하고,\n\u002F\u002F 그 외의 경우 (예: 개발 환경)에는 루트 경로를 사용합니다.\nconst isProduction = process.env.NODE_ENV === 'production'\nconst githubRepoName = '\u002Fd-korea-law\u002F' \u002F\u002F 본인의 GitHub 저장소 이름으로 변경하세요 (예: '\u002Fmy-project-name\u002F')\nconst baseURL = isProduction ? githubRepoName : '\u002F'\n\nexport default defineNuxtConfig({\n  \u002F\u002F SSR(서버 사이드 렌더링)을 비활성화하여 정적 사이트로 빌드합니다.\n  \u002F\u002F GitHub Pages와 같은 정적 호스팅 환경에 적합합니다.\n  ssr: false,\n\n  app: {\n    \u002F\u002F 애플리케이션의 모든 자산(이미지, CSS, JS) 및 클라이언트 측 라우팅의 기본 URL을 설정합니다.\n    \u002F\u002F GitHub Pages의 서브 경로를 반영하여 자산 및 라우팅 경로가 올바르게 로드되도록 합니다.\n    baseURL: baseURL,\n    \u002F\u002F head: {\n    \u002F\u002F   \u002F\u002F \u003Cbase href=\"...\"> 태그를 설정하여 모든 상대 URL의 기준을 변경할 수 있으나,\n    \u002F\u002F   \u002F\u002F Nuxt 3에서는 `app.baseURL` 설정이 더 권장되고 효과적입니다.\n    \u002F\u002F }\n  },\n\n  \u002F\u002F Nuxt 3에서는 `ssr: false`와 `nuxt build` 명령으로 정적 파일을 생성합니다.\n  \u002F\u002F `output.publicDir` 등의 설정은 빌드 결과물의 위치를 정의할 때 사용됩니다.\n  \u002F\u002F `_nuxt` 폴더 등의 자산 경로가 `baseURL`에 따라 올바르게 생성됩니다.\n\n  \u002F\u002F 기타 Nuxt 설정 (예: CSS, 모듈 등)은 필요에 따라 추가합니다.\n  css: ['~\u002Fassets\u002Fcss\u002Fmain.scss'], \u002F\u002F 예시: 전역 CSS 파일 경로\n  \u002F\u002F modules: [],\n  \u002F\u002F plugins: [],\n  \u002F\u002F build: {},\n})\n```\n\n## 빌드 및 배포\n\n`nuxt.config.ts` 파일 수정 후, 다음 단계를 통해 프로젝트를 빌드하고 배포합니다.\n\n1.  **프로젝트 빌드**: 터미널에서 다음 명령어를 실행하여 정적 파일을 생성합니다.\n    ```bash\n    npm run build\n    # 또는 pnpm run build, yarn build, bun run build\n    ```\n    이 명령어를 실행하면 기본적으로 프로젝트 루트에 `.output\u002Fpublic` (또는 `dist` 등) 폴더가 생성되며, 이 안에 배포 가능한 정적 파일들이 포함됩니다.\n\n2.  **GitHub Pages 배포**: 생성된 `.output\u002Fpublic` 폴더의 내용을 GitHub Pages 배포 브랜치(일반적으로 `gh-pages` 브랜치 또는 `main` 브랜치의 `\u002Fdocs` 폴더)에 업로드합니다.\n\n    *   **수동 배포**: `.output\u002Fpublic` 내용을 복사하여 배포 브랜치에 커밋하고 푸시합니다.\n    *   **GitHub Actions**: `.github\u002Fworkflows\u002Fdeploy.yml` 파일에서 빌드 후 `.output\u002Fpublic` 폴더를 GitHub Pages로 배포하도록 설정할 수 있습니다. `actions\u002Fupload-pages-artifact` 및 `actions\u002Fdeploy-pages` 액션을 활용하면 자동화된 배포 파이프라인을 구축할 수 있습니다.\n\n## 흔히 하는 실수 및 주의점\n\n*   **저장소 이름 오타**: `baseURL`에 설정하는 저장소 이름이 GitHub 저장소 이름과 정확히 일치해야 합니다. 대소문자도 구분하니 주의하십시오.\n*   **배포 브랜치 확인**: GitHub 저장소 설정(`Settings` > `Pages`)에서 올바른 브랜치(예: `gh-pages` 또는 `main` 브랜치의 `\u002Fdocs` 폴더)를 소스로 선택했는지 확인해야 합니다.\n*   **환경 변수 활용**: 여러 환경에서 다른 `baseURL`을 사용해야 할 경우, `process.env.NUXT_APP_BASE_URL`과 같은 환경 변수를 사용하여 유연하게 관리하는 것이 좋습니다. 예를 들어, `package.json` 스크립트에서 `NUXT_APP_BASE_URL=\u002Fyour-repo\u002F npm run build`와 같이 설정할 수 있습니다.\n*   **Nuxt 버전**: 이 가이드는 Nuxt 3를 기준으로 작성되었습니다. Nuxt 2에서는 `router.base` 옵션을 주로 사용했습니다. 사용하는 Nuxt 버전에 따라 설정 방식에 약간의 차이가 있을 수 있으니 공식 문서를 참고하는 것이 좋습니다.","2026-08-26T14:01:53.445+09:00",[10,11,12,13,14,15,16,17],"GitHub Pages","Nuxt-js","baseURL","기술 가이드","배포","자산 경로","정적 사이트","프론트엔드",1788152657249]