跳转到内容

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

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

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

方案

名为“方法”的部分

此方法配置 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）

  1. 添加 Vite Rollup 输出选项。

    修改你的 astro.config.mjs 文件，包含以下 vite.build.rollupOptions.output 配置。你可以在这里使用 Rollup 的 entryFileNames、chunkFileNames 和 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]',
            },
          },
        },
      },
    });

    此示例使用以下文件名占位符

    • [name]：文件的原始名称（不包括扩展名和路径）。
    • [hash]：为文件生成的内容哈希，对缓存清除至关重要。你也可以指定长度，例如 [hash:8]。这确保了当你更新资源时，文件名会改变，从而强制浏览器下载新版本，而不是提供一个过时的缓存版本。
    • [extname]：原始文件扩展名，包括前面的点（例如 .js、.css、.svg）。

    有关这些选项的可用占位符和高级模式的完整列表，请参阅 Rollup 配置文档。

  2. 构建你的项目。

    由于这些文件名自定义仅适用于生产构建输出，因此你需要运行项目的构建命令

    终端窗口
    npm run build

  3. 构建完成后，检查你的输出目录（默认为 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 文件和公共资源）
贡献 社区 赞助