@astrojs/ partytown

这个 Astro 整合在你的 Astro 项目中启用了 Partytown。

¥This Astro integration enables Partytown in your Astro project.

为什么选择 Astro Partytown

¥Why Astro Partytown

Partytown 是一个延迟加载库，可帮助将资源密集型脚本重新定位到网络工作者中，并从主线程中移出。

¥Partytown is a lazy-loaded library to help relocate resource intensive scripts into a web worker, and off of the main thread.

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

¥If you’re using third-party scripts for things like analytics or ads, Partytown is a great way to make sure that they don’t slow down your site.

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

¥The Astro Partytown integration installs Partytown for you and makes sure it’s enabled on all of your pages.

安装

¥Installation

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

¥Astro includes an astro add command to automate the setup of official integrations. If you prefer, you can install integrations manually instead.

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

¥Run one of the following commands in a new terminal window.

npx astro add partytown

pnpm astro add partytown

yarn astro add partytown

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

¥If you run into any issues, feel free to report them to us on GitHub and try the manual installation steps below.

手动安装

¥Manual Install

首先，安装 @astrojs/partytown 包：

¥First, install the @astrojs/partytown package:

npm install @astrojs/partytown

pnpm add @astrojs/partytown

yarn add @astrojs/partytown

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

¥Then, apply the integration to your astro.config.* file using the integrations property:

import { defineConfig } from 'astro/config';
import partytown from '@astrojs/partytown';

export default defineConfig({
  // ...
  integrations: [partytown()],
});

用法

¥Usage

Partytown 应该准备好零配置。如果你的网站上已有第 3 方脚本，请尝试添加 type="text/partytown" 属性：

¥Partytown should be ready to go with zero config. If you have an existing 3rd party script on your site, try adding the type="text/partytown" attribute:

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

如果你从你的浏览器的开发工具打开 “网络” 选项卡，你应该看到 partytown 代理拦截此请求。

¥If you open the “Network” tab from your browser’s dev tools, you should see the partytown proxy intercepting this request.

配置

¥Configuration

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

¥To configure this integration, pass a ‘config’ object to the partytown() function call in astro.config.mjs.

export default defineConfig({
  // ...
  integrations: [
    partytown({
      config: {
        // options go here
      },
    }),
  ],
});

这与 Partytown 配置对象类似，所有选项都可以在 partytown.config 中设置。此页面介绍了 Astro 项目的一些常用配置选项。

¥This mirrors the Partytown config object and all options can be set in partytown.config. Some common configuration options for Astro projects are described on this page.

启用调试模式

¥Enabling debug mode

Partytown 附带 debug 模式；通过将 true 或 false 传递给 config.debug 来启用或禁用它。如果启用 debug 模式，则会将详细日志输出到浏览器控制台。

¥Partytown ships with a debug mode; enable or disable it by passing true or false to config.debug. If debug mode is enabled, it will output detailed logs to the browser console.

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

¥If this option isn’t set, debug mode will be on by default in dev or preview mode.

export default defineConfig({
  // ...
  integrations: [
    partytown({
      // Example: Disable debug mode.
      config: { debug: false },
    }),
  ],
});

转发变量

¥Forwarding variables

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

¥Third-party scripts typically add variables to the window object so that you can communicate with them throughout your site. But when a script is loaded in a web-worker, it doesn’t have access to that global window object.

为了解决这个问题，Partytown 可以将 “patch” 变量添加到全局窗口对象并将它们转发到适当的脚本。

¥To solve this, Partytown can “patch” variables to the global window object and forward them to the appropriate script.

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

¥You can specify which variables to forward with the config.forward option. Read more in Partytown’s documentation.

export default defineConfig({
  // ...
  integrations: [
    partytown({
      // Example: Add dataLayer.push as a forwarding-event.
      config: {
        forward: ['dataLayer.push'],
      },
    }),
  ],
});

代理请求

¥Proxying requests

某些第三方脚本可能需要 proxying 到 config.resolveUrl()，它们在 Service Worker 中运行。你可以设置此配置选项以检查特定 URL，并可选择返回代理 URL：

¥Some third-party scripts may require proxying through config.resolveUrl(), which runs inside the service worker. You can set this configuration option to check for a specific URL, and optionally return a proxied URL instead:

export default defineConfig({
  // ...
  integrations: [
    partytown({
      // Example: proxy Facebook's analytics script
      config: {
        resolveUrl: (url) => {
          const proxyMap = {
            "connect.facebook.net": "my-proxy.com"
          }
          url.hostname = proxyMap[url.hostname] || url.hostname;
          return url;
        },
      }
    }),
  ],
});

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

¥However since the config object is serialized when sent to the client, some limitations on functions passed to your configuration apply:

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

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

¥In some advanced use cases, you may need to pass data to this function while initializing Partytown. To do so, you can set resolveUrl() on window.partytown instead of the integration config:

---
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;
    },
  };
`} />