Cloudflare 中文文档
Pages
Cloudflare 中文文档
Pages
编辑这个页面
跳转官方原文档
Set theme to dark (⇧+D)
  1. Products
  2. Pages
  3. Functions
  4. Pages Plugins

页面插件

Cloudflare 维护了许多官方 Pages 插件，供你在 Pages 项目中使用：

​​ Author a Pages Plugin

A Pages Plugin is a Pages Functions distributable which includes built-in routing and functionality. Developers can include a Plugin as a part of their Pages project wherever they chose, and can pass it some configuration options. The full power of Functions is available to Plugins, including middleware, parameterized routes, and static assets.

For example, a Pages Plugin could:

  • Intercept HTML pages and inject in a third-party script.
  • Proxy a third-party service’s API.
  • Validate authorization headers.
  • Provide a full admin web app experience.
  • Store data in KV or Durable Objects.
  • Server-side render (SSR) webpages with data from a CMS.
  • Report errors and track performance.

A Pages Plugin is essentially a library that developers can use to augment their existing Pages project with a deep integration to Functions.

​​ Use a Pages Plugin

Developers can enhance their projects by mounting a Pages Plugin at a route of their application. Plugins will provide instructions of where they should typically be mounted (for example, an admin interface might be mounted at functions/admin/[[path]].ts, and an error logger might be mounted at functions/_middleware.ts). Additionally, each Plugin may take some configuration (for example, with an API token).

​​ 静态表格示例

在本例中，你将构建一个页面插件，然后将其包含在一个项目中。

第一个插件应

  • 拦截 HTML 表格。
  • 将表单提交存储在 KV 中。
  • 用开发人员的自定义回复来响应提交。

​​ 1.创建新的页面插件

创建包含以下内容的 package.json：

在我们的示例中，dist/index.js 将是插件的入口点。这是 Wrangler 使用 npm run build 命令生成的文件。将 dist/ 目录添加到 .gitignore。

接下来，创建一个 functions 目录并开始编写插件。functions 文件夹将被开发人员挂载到某个路径，因此请考虑如何构建你的文件。一般来说

  • 如果希望插件在开发者选择的单一路由(例如 /foo)上运行，则创建一个 functions/index.ts 文件。
  • 如果你希望你的插件被挂载并为特定路径(例如，/admin/login 和/admin/dashboard)以外的所有请求提供服务，请创建一个functions/[[路径]].ts文件。
  • 如果想让插件拦截请求，但在其他函数或项目的静态资产上进行回退，请创建一个 functions/_middleware.ts 文件。

你可以根据需要自由使用不同的文件。插件的结构与现在 Pages 项目中的函数完全相同，不同之处在于处理程序会收到其参数对象的一个新属性 pluginArgs。该属性是开发人员在安装插件时传递的初始化参数。你可以用它来接收 API 标记、KV/Durable Object 命名空间或插件运行所需的任何其他内容。

回到静态表单的例子，如果你想拦截请求并覆盖 HTML 表单的行为，你需要创建一个 functions/_middleware.ts。这样，开发人员就可以在单个路由或整个项目中安装你的插件。

​​ 2. 输入你的页面插件

为了创造良好的开发体验，你应该考虑在插件中添加 TypeScript 类型。这样，开发人员就可以使用集成开发环境的自动完成功能，并确保包含你期望的所有参数。

在 index.d.ts中，导出一个接收pluginArgs并返回PagesFunction的函数。在静态表单示例中，你需要两个属性：kv(一个 KV 命名空间)和respondWith(一个接收带有formData属性(FormData)的对象并返回Response的Promise的函数)：

​​ 3. 测试页面插件

我们仍在努力为页面插件作者创建良好的测试体验。请耐心等待我们完成所有工作。在此期间，你可以创建一个示例项目，并手动包含你的插件进行测试。

​​ 4. 发布页面插件

你可以随意发布你的插件。常用的方式包括在 npm 上发布，在我们的 Developer Discord 的 #what-i-built 或 #pages-discussions 频道中展示，以及在 GitHub 上开源。

确保包含生成的 dist/ 目录、你的类型 index.d.ts 以及包含开发人员如何使用插件的说明的 README.md。

​​ 5. Install your Pages Plugin

If you want to include a Pages Plugin in your application, you need to first install that Plugin to your project.

If you are not yet using npm in your project, run npm init to create a package.json file. The Plugin’s README.md will typically include an installation command (for example, npm install --save @cloudflare/static-form-interceptor).

​​ 6. Mount your Pages Plugin

The README.md of the Plugin will likely include instructions for how to mount the Plugin in your application. You will need to:

  1. Create a functions directory, if you do not already have one.
  2. Decide where you want this Plugin to run and create a corresponding file in the functions directory.
  3. Import the Plugin and export an onRequest method in this file, initializing the Plugin with any arguments it requires.

In the static form example, the Plugin you have created already was created as a middleware. This means it can run on either a single route, or across your entire project. If you had a single contact form on your website at /contact, you could create a functions/contact.ts file to intercept just that route. You could also create a functions/_middleware.ts file to intercept all other routes and any other future forms you might create. As the developer, you can choose where this Plugin can run.

A Plugin’s default export is a function which takes the same context parameter that a normal Pages Functions handler is given.

​​ 7. Test your Pages Plugin

You can use wrangler pages dev to test a Pages project, including any Plugins you have installed. Remember to include any KV bindings and environment variables that the Plugin is expecting.

With your Plugin mounted on the /contact route, a corresponding HTML file might look like this:

Your plugin should pick up the data-static-form-name="contact" attribute, set the method="POST", inject in an <input type="hidden" name="static-form-name" value="contact" /> element, and capture POST submissions.

​​ 8. Deploy your Pages project

Make sure the new Plugin has been added to your package.json and that everything works locally as you would expect. You can then git commit and git push to trigger a Cloudflare Pages deployment.

If you experience any problems with any one Plugin, file an issue on that Plugin’s bug tracker.

If you experience any problems with Plugins in general, we would appreciate your feedback in the #pages-discussions channel in Discord! We are excited to see what you build with Plugins and welcome any feedback about the authoring or developer experience. Let us know in the Discord channel if there is anything you need to make Plugins even more powerful.

​​ 链接你的插件

最后，与一般的 Pages Functions 一样，也可以将 Plugins 链接起来，以组合不同的功能。在文件系统中较高位置定义的中间件将在其他处理程序之前运行，单个文件可以像这样在数组中将多个函数串联起来：