빌드 출력의 파일 이름 사용자 정의하기

기본적으로 astro build 명령은 프로젝트 소스에서 빌드한 자산 (예: src/ 디렉터리에 있는 JavaScript 및 CSS 파일)을 _astro 디렉터리에 해시된 파일 이름으로 (예: _astro/index.DRf8L97S.js) 출력하여 장기 캐싱에 유용하게 사용할 수 있습니다.

일반적으로는 필요하지 않지만 필요한 경우 출력 파일 이름을 사용자 정의할 수 있습니다. 예를 들어 광고 차단기를 트리거할 수 있는 이름의 스크립트 (예: ads.js)가 있거나 특정 명명 규칙에 따라 자산을 구성하려는 경우 유용할 수 있습니다. Rollup의 output 옵션을 사용자 정의하면 프로젝트의 빌드 구조를 더 잘 제어할 수 있어 특정 조직 또는 배포 요구 사항을 충족할 수 있습니다.

레시피

이 레시피는 다음과 같은 구조 및 명명 패턴으로 빌드된 자산을 출력하기 위해 vite.build.rollupOptions를 구성합니다.

JavaScript 항목 파일 (예: 페이지 또는 레이아웃과 직접 연결된 스크립트): dist/js/[name]-[hash].js
JavaScript 코드 분할 청크 (예: 동적으로 가져온 컴포넌트 또는 공유 모듈): dist/js/chunks/[name]-[hash].js
기타 자산 (예: CSS, 이미지, 글꼴): dist/static/[name]-[hash][extname] (예: dist/static/styles-a1b2c3d4.css, dist/static/logo-e5f6g7h8.svg)

Vite Rollup Output 옵션을 추가합니다.

다음 vite.build.rollupOptions.output 구성을 포함하도록 astro.config.mjs를 수정합니다. 여기에서 Rollup의 entryFileNames, chunkFileNames, assetFileNames를 사용하여 자산의 사용자 정의 명명 패턴을 정의할 수 있습니다.
astro.config.mjs
```
import { defineConfig } from 'astro/config';

export default defineConfig({
  // ...
  vite: {
    build: {
      rollupOptions: {
        output: {
          // `outDir`에 상대적인 경로 이름
          entryFileNames: 'js/[name]-[hash].js',
          chunkFileNames: 'js/chunks/[name]-[hash].js',
          assetFileNames: 'static/[name]-[hash][extname]',
        },
      },
    },
  },
});
```
이 예시는 다음과 같은 파일 이름 자리 표시자를 사용합니다.
- [name]: 파일의 원래 이름 (확장자 및 경로 없음)
- [hash]: 파일에 대해 생성된 콘텐츠 기반 해시로, 캐시 버스팅에 중요합니다. 길이를 지정할 수도 있습니다 (예: [hash:8]). 이렇게 하면 자산을 업데이트할 때 파일 이름이 변경되어 브라우저가 오래된 캐시 버전을 제공하는 대신 새 버전을 다운로드하도록 할 수 있습니다.
- [extname]: 선행 점을 포함한 원본 파일 확장자 (예: .js, .css, .svg)
이러한 옵션에 사용할 수 있는 자리 표시자 및 고급 패턴의 전체 목록은 Rollup 구성 문서를 참조하세요.
프로젝트를 빌드합니다.

이러한 파일 이름 사용자 정의는 프로덕션 빌드 출력에만 적용되므로 프로젝트의 빌드 명령을 실행해야 합니다.
- npm
- pnpm
- Yarn
터미널 창
npm run build
터미널 창
pnpm build
터미널 창
yarn build
빌드가 완료되면 출력 디렉터리 (기본적으로 dist/)를 확인합니다.

프로젝트 src의 빌드 자산이 새 패턴에 따라 이름이 지정되고 구성되었는지 확인합니다. (public/ 디렉터리의 파일은 출력 디렉터리에 직접 복사되며 이러한 Rollup 명명 옵션의 영향을 받지 않습니다.)

프로젝트의 콘텐츠에 따라 빌드 폴더는 이제 다음과 같은 모습이 됩니다.
- 디렉터리dist/
  - 디렉터리js/
    index-a1b2c3d4.js
    디렉터리chunks/
    common-e5f6g7h8.js
  - 디렉터리img/
    logo-i9j0k1l2.png
  - 디렉터리fonts/
    myfont-q2w3e4r5.woff2
  - 디렉터리static_assets/
    styles-m3n4o5p6.css
  - index.html
  - 디렉터리about/
    index.html
  - … (기타 HTML 파일 및 공개 자산)

기여하기 커뮤니티 후원하기