[{"data":1,"prerenderedAt":18},["ShallowReactive",2],{"$f4ddbF7whARBKDxeVS5FQp6ZrtqT4sT4vAl8-4_pz9TY":3},{"uuid":4,"title":5,"summary":6,"content":7,"createdAt":8,"tags":9},"e4b5a71f-937f-4f86-a6eb-bd51f7f52183","GitHub Pages에 정적 사이트 배포 시 자산 경로(Asset Path) 깨짐 문제 해결하기","GitHub Pages에 Next.js와 같은 정적 사이트를 배포할 때, 저장소 이름을 포함하는 서브 경로(예: `username.github.io\u002Frepository-name\u002F`)로 인해 이미지, 폰트 등 자산 경로가 올바르게 로드되지 않는 문제가 발생합니다. 이 문제는 `next.config.js` 파일에 `basePath`를 설정하고, 코드 내에서 자산 경로를 이 `basePath`에 맞춰 수정함으로써 해결할 수 있습니다.","## 1. 문제의 원인: GitHub Pages의 서브 경로 배포\n\nGitHub Pages는 보통 `username.github.io` 또는 `organization.github.io`와 같은 도메인 루트에 배포되거나, 특정 저장소의 경우 `username.github.io\u002Frepository-name\u002F`과 같은 서브 경로에 배포됩니다. Next.js의 `output: 'export'` 기능을 사용하여 정적 사이트를 빌드하면, 기본적으로 모든 자산 경로가 애플리케이션의 루트(`\u002F`)를 기준으로 생성됩니다.\n\n예를 들어, `public\u002Fimages\u002Flogo.png` 파일은 빌드 후 HTML에서 `\u002Fimages\u002Flogo.png`로 참조될 것입니다. 하지만 이 사이트가 `username.github.io\u002Fmy-repo\u002F` 경로에 배포되면, 브라우저는 `username.github.io\u002Fimages\u002Flogo.png`에서 자산을 찾으려 시도하여 404 에러를 발생시키고 이미지가 깨지는 현상이 나타납니다.\n\n## 2. 해결 방법: `basePath` 설정 (Next.js 기준)\n\nNext.js는 이러한 서브 경로 배포 환경을 지원하기 위해 `basePath` 설정을 제공합니다. `next.config.js` 파일에 `basePath`를 저장소 이름과 동일하게 설정하면, Next.js는 내부적으로 모든 라우팅 및 자산 경로를 이 `basePath`에 맞춰 재작성합니다.\n\n`next.config.js` 파일을 다음과 같이 수정하세요:\n\n```javascript\n\u002F** @type {import('next').NextConfig} *\u002F\nconst nextConfig = {\n  output: 'export', \u002F\u002F 정적 HTML 파일로 내보내기 위해 필요\n  basePath: '\u002Fframe-pick', \u002F\u002F GitHub 저장소 이름과 동일하게 설정\n  images: {\n    unoptimized: true, \u002F\u002F Next.js Image 컴포넌트를 정적 내보내기에서 사용하려면 필요\n  },\n  \u002F\u002F 기타 Next.js 설정...\n};\n\nmodule.exports = nextConfig;\n```\n\n여기서 `basePath`는 배포될 GitHub 저장소의 이름(예: `HDomi\u002Fframe-pick`의 경우 `\u002Fframe-pick`)과 일치해야 합니다. `unoptimized: true`는 `next\u002Fimage` 컴포넌트를 사용하는 경우 정적 사이트에서 이미지 최적화 기능을 비활성화하고 이미지가 올바르게 로드되도록 합니다.\n\n## 3. 코드 내 자산 경로 수정\n\n`basePath`를 설정했더라도, `public` 폴더 내의 자산을 코드에서 직접 참조할 때는 수동으로 `basePath`를 경로에 추가해야 합니다. Next.js는 `public` 폴더 내의 파일에 대해 `basePath`를 자동으로 접두사로 붙여주지 않습니다.\n\n이를 위해 `process.env.NEXT_PUBLIC_BASE_PATH`와 같은 환경 변수를 활용하는 것이 좋습니다. `next.config.js`에 설정한 `basePath` 값을 `NEXT_PUBLIC_BASE_PATH` 환경 변수로 노출할 수 있습니다.\n\n예를 들어, `public\u002Fstickers\u002Farrow.svg` 파일을 로드하는 경우:\n\n```typescript\n\u002F\u002F next.config.js에 basePath가 '\u002Fframe-pick'으로 설정되어 있다고 가정\n\n\u002F\u002F 1. 환경 변수를 통해 basePath를 동적으로 가져와 사용\nconst BASE_PATH = process.env.NEXT_PUBLIC_BASE_PATH || ''; \u002F\u002F 기본값 설정\n\n\u002F\u002F 2. Fabric.js의 loadSVGFromURL 함수를 사용하여 SVG 로드\n\u002F\u002F 'loadSVGFromURL'과 같이 직접 URL을 지정하는 경우 basePath를 명시적으로 포함해야 합니다.\nfabric.loadSVGFromURL(`${BASE_PATH}\u002Fstickers\u002Farrow.svg`, (objects, options) => {\n  const svg = fabric.util.groupSVGElements(objects, options);\n  \u002F\u002F 캔버스에 SVG 추가 또는 다른 작업 수행\n  canvas.add(svg).renderAll();\n});\n\n\u002F\u002F 3. 일반적인 이미지 태그나 CSS 배경 이미지 경로 설정 시\n\u002F\u002F \u003Cimg src={`${BASE_PATH}\u002Fimages\u002Fmy-logo.png`} alt=\"Logo\" \u002F>\n\u002F\u002F 혹은 CSS: background-image: url('${BASE_PATH}\u002Fstyles\u002Fbackground.jpg');\n```\n\nNext.js의 `Image` 컴포넌트는 `basePath`가 설정되어 있으면 자동으로 처리하는 경우가 많지만, `public` 폴더의 자산에 대한 직접적인 `\u003Cimg>` 태그나 CSS `url()` 참조, 그리고 Fabric.js의 `loadSVGFromURL`과 같이 JavaScript에서 동적으로 로드하는 경우에는 위와 같이 `basePath`를 포함하여 경로를 구성해야 합니다.\n\n## 4. 배포 워크플로우 수정 (선택 사항)\n\nGitHub Actions를 사용하여 배포하는 경우, `.github\u002Fworkflows\u002Fdeploy.yml` 파일에서 `NEXT_PUBLIC_BASE_PATH` 환경 변수를 설정하여 빌드 시점에 `basePath`를 주입할 수 있습니다. 이는 `next.config.js`에서 `basePath`를 직접 설정하는 것과 별개로, 코드 내에서 `process.env.NEXT_PUBLIC_BASE_PATH`를 사용할 때 유용합니다.\n\n```yaml\n# .github\u002Fworkflows\u002Fdeploy.yml 예시\nname: Deploy to GitHub Pages\n\non:\n  push:\n    branches:\n      - main\n\njobs:\n  build-and-deploy:\n    runs-on: ubuntu-latest\n\n    steps:\n      - name: Checkout repository\n        uses: actions\u002Fcheckout@v4\n\n      - name: Setup Node.js\n        uses: actions\u002Fsetup-node@v4\n        with:\n          node-version: 20 # 또는 프로젝트에 맞는 Node.js 버전\n          cache: 'pnpm'\n\n      - name: Install dependencies\n        run: pnpm install\n\n      - name: Build project\n        run: pnpm build\n        env:\n          NEXT_PUBLIC_BASE_PATH: \u002Fframe-pick # 여기에 저장소 이름 명시\n          # 기타 필요한 환경 변수...\n\n      - name: Deploy to GitHub Pages\n        uses: peaceiris\u002Factions-gh-pages@v3\n        if: ${{ github.ref == 'refs\u002Fheads\u002Fmain' }}\n        with:\n          github_token: ${{ secrets.GITHUB_TOKEN }}\n          publish_dir: .\u002Fout # Next.js static export의 기본 출력 디렉토리\n          # 기타 배포 설정...\n```\n\n## 5. 확인 방법\n\n배포 후 웹 브라우저의 개발자 도구(F12)를 열어 \"Network\" 탭을 확인하세요. 깨졌던 자산들이 올바른 경로(예: `username.github.io\u002Fframe-pick\u002Fimages\u002Flogo.png`)로 요청되고 200 OK 응답을 받는지 확인합니다. CSS 파일이나 JavaScript 콘솔에 경로 관련 오류가 없는지도 함께 확인하면 좋습니다.\n\n## 6. 흔히 하는 실수 및 주의점\n\n*   **`basePath` 오타**: `next.config.js`의 `basePath` 값이 GitHub 저장소 이름과 정확히 일치하는지 확인하세요. 대소문자도 중요합니다.\n*   **캐싱 문제**: 배포 후에도 자산 경로가 깨져 보인다면, 브라우저 캐시를 지우거나 시크릿 모드(InPrivate)로 접속하여 확인해보세요. CDN을 사용하는 경우 CDN 캐시를 무효화해야 할 수도 있습니다.\n*   **`next\u002Fimage` 컴포넌트**: `output: 'export'`와 함께 `next\u002Fimage`를 사용하는 경우, `next.config.js`에 `images: { unoptimized: true }`를 반드시 추가해야 합니다. 이 설정을 누락하면 이미지가 로드되지 않을 수 있습니다.\n*   **절대 경로 사용**: `basePath`를 설정한 후에는 `public` 폴더의 자산을 참조할 때 `.\u002Fimage.png`와 같은 상대 경로보다는 `\u002F${process.env.NEXT_PUBLIC_BASE_PATH}\u002Fimage.png`와 같은 절대 경로를 사용하는 것이 일관성과 안정성을 높이는 데 도움이 됩니다.\n*   **다른 프레임워크**: Next.js가 아닌 다른 정적 사이트 생성기(예: Gatsby, Astro, Vite 등)를 사용하는 경우, 각 프레임워크가 제공하는 `basePath` 또는 `publicPath`와 같은 유사한 설정을 찾아 적용해야 합니다. 환경에 따라 설정 방식이 다를 수 있으니 해당 프레임워크의 문서를 확인하는 것이 중요합니다.","2026-08-21T14:01:21.001+09:00",[10,11,12,13,14,15,16,17],"404 에러","GitHub Pages","Next-js","basePath","기술 가이드","배포","자산 경로","정적 사이트",1788152657404]