@astrojs/ partytown

v2.1.4 GitHub npm 更新日志

此 Astro 集成 允许你在 Astro 项目中启用 Partytown。

为什么是 Astro Partytown

Partytown 是一个延迟加载的库，可以帮助将资源密集型脚本转移到 web worker 中，并且从主线程中移除。

如果你使用第三方脚本进行分析或广告等操作，Partytown 是确保它们不会减慢网站速度的绝佳方法。

Astro Partytown 集成会为你安装 Partytown 并确保它在所有页面上启用。

安装

Astro 包含了一个 astro add 命令，用于自动设置官方集成。如果你愿意，可以改为手动安装集成。

在新的终端窗口中运行以下其中一个命令。

npx astro add partytown

pnpm astro add partytown

yarn astro add partytown

如果你遇到任何问题，请随时在 GitHub 上向我们报告并尝试下面的手动安装步骤。

手动安装

首先，安装 @astrojs/partytown 包:

npm install @astrojs/partytown

pnpm add @astrojs/partytown

yarn add @astrojs/partytown

然后，使用 integrations 属性将集成应用到你的 astro.config.* 文件中：

import { defineConfig } from 'astro/config';
import partytown from '@astrojs/partytown';
export default defineConfig({
  // ...
  integrations: [partytown()],
});

使用

Partytown 应该可以零配置使用。如果你网站上已经有现成的第三方脚本，试试添加 type="text/partytown" 属性：

<script type="text/partytown" src="fancy-analytics.js"></script>

如果你打开浏览器开发者工具的“网络 Network”标签，你应该可以看到 partytown 代理拦截了这个请求。

配置

要配置此集成，请将一个 ‘config’ 对象传递给 astro.config.mjs 中的 partytown() 函数调用。

export default defineConfig({
  // ...
  integrations: [
    partytown({
      config: {
        // 配置项在这
      },
    }),
  ],
});

这与 Partytown 配置对象相对应。并且所有选项都可以在 partytown.config 中设置。本页描述了适用于 Astro 项目的常见配置选项。

启用 debug 模式

Partytown 自带一个 debug 模式；通过向 config.debug 传入 true 或 false 来启用或禁用它。如果启用了debug 模式，它会向浏览器控制台输出详细的日志。

如果不设置此选项，在 dev 或 preview 模式下，debug 模式默认启用。

export default defineConfig({
  // ...
  integrations: [
    partytown({
      // 示例：禁用调试模式。
      config: { debug: false },
    }),
  ],
});

转发变量

第三方脚本通常会向 window 对象添加变量，以便你可以在整个站点与它们通信。但是当一个脚本在 web worker 中加载时，它无法访问全局的 window 对象。

为了解决这个问题，Partytown 可以“打补丁”变量到全局 window 对象并将它们转发到适当的脚本。

你可以使用 config.forward 选项指定要转发的变量。在 Partytown 的文档中了解更多信息。

export default defineConfig({
  // ...
  integrations: [
    partytown({
      // 示例：将 dataLayer.push 作为 forwarding-event 添加。
      config: {
        forward: ['dataLayer.push'],
      },
    }),
  ],
});

代理请求

某些第三方脚本可能需要通过运行在 service worker 内的 config.resolveUrl() 进行代理。你可以设置此配置选项以检查特定 URL，并可选择返回一个被代理的 URL：

export default defineConfig({
  // ...
  integrations: [
    partytown({
      // 示例：代理 Facebook 的分析脚本
      config: {
        resolveUrl: (url) => {
          const proxyMap = {
            "connect.facebook.net": "my-proxy.com"
          }
          url.hostname = proxyMap[url.hostname] || url.hostname;
          return url;
        },
      }
    }),
  ],
});

但是由于 config 对象在发送到客户端时会被序列化，因此对传入配置的函数存在一些限制：

函数不能引用函数作用域之外的任何内容。
函数只能用 JavaScript 编写。

在一些高级用例中，你可能需要在初始化 Partytown 时向此函数传递数据。为此，你可以将 resolveUrl() 设置在 window.partytown 上，而不是集成配置中：

---
const proxyMap = {
  "connect.facebook.net": "my-proxy.com"
};
---
<script is:inline set:html={`
  window.partytown = {
    resolveUrl: (url) => {
      const proxyMap = ${JSON.stringify(proxyMap)};
      url.hostname = proxyMap[url.hostname] || url.hostname;
      return url;
    },
  };
`} />