自定义构建输出中的文件名

默认情况下，astro build 命令会将你在 你的项目源 中构建的资源（例如位于 src/ 目录中的 JavaScript 和 CSS 文件）输出到 _astro 目录中，并使用哈希文件名（例如 _astro/index.DRf8L97S.js），这非常适合长期缓存。

¥By default, the astro build command outputs your built assets from your project source, like JavaScript and CSS files located in the src/ directory, into an _astro directory with hashed filenames (e.g. _astro/index.DRf8L97S.js) which are excellent for long-term caching.

虽然通常情况下没有必要，但你可以在需要时自定义输出文件名。例如，如果你的脚本名称可能会触发广告拦截器（例如 ads.js），或者你想使用特定的命名约定来组织你的资源，这可能会很有帮助。通过自定义 Rollup 输出选项，你可以更好地控制项目的构建结构，从而满足特定的组织或部署需求。

¥Although it is normally not necessary, you can customise the output file names when needed. For example, this can be helpful if you have scripts with names that might trigger ad blockers (e.g. ads.js), or if you want to organize your assets with a particular naming convention. By customizing Rollup output options, you can gain more control over your project’s build structure, allowing you to meet specific organizational or deployment requirements.

秘诀

¥Recipe

此方法将 vite.build.rollupOptions 配置为输出具有以下结构和命名模式的构建资源：

¥This recipe configures vite.build.rollupOptions to output built assets with the following structure and naming pattern:

• 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）

1. Add Vite Rollup Output Options.

   Modify your astro.config.mjs to include the following vite.build.rollupOptions.output configuration. This is where you can define the custom naming patterns for your assets using Rollup’s entryFileNames, chunkFileNames, and assetFileNames:

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   
   export default defineConfig({
     // ...
     vite: {
       build: {
         rollupOptions: {
           output: {
             // path names relative to `outDir`
             entryFileNames: 'js/[name]-[hash].js',
             chunkFileNames: 'js/chunks/[name]-[hash].js',
             assetFileNames: 'static/[name]-[hash][extname]',
           },
         },
       },
     },
   });

   This example uses the following file name placeholders:

   • [name]: The original name of the file (without the extension and path).

   • [hash]: A content-based hash generated for the file, crucial for cache busting. You can also specify a length, e.g. [hash:8]. This ensures that when you update an asset, the filename changes, forcing browsers to download the new version instead of serving a stale cached version.

   • [extname]: The original file extension, including the leading dot (e.g. .js, .css, .svg).

   For a full list of available placeholders and advanced patterns for these options, refer to the Rollup configuration documentation.

2. Build your project.

   Since these filename customizations apply to the production build output only, you will need to run your project’s build command:

   npm

   npm run build

   pnpm

   pnpm build

   Yarn

   yarn build

3. After the build completes, inspect your output directory (dist/ by default).

   Verify that the build assets from your project src are named and organized according to the new patterns. (Files from your public/ directory are copied directly to the output directory and are not affected by these Rollup naming options.)

   Depending on your project’s specific contents, your build folder will now look something like this:

   • Directorydist/

     • Directoryjs/

       • index-a1b2c3d4.js
       • Directorychunks/

         • common-e5f6g7h8.js
     • Directoryimg/

       • logo-i9j0k1l2.png
     • Directoryfonts/

       • myfont-q2w3e4r5.woff2
     • Directorystatic_assets/

       • styles-m3n4o5p6.css
     • index.html
     • Directoryabout/

       • index.html
     • … (other HTML files and public assets)