Cloudflare Pages 适配器

Qwik City Cloudflare Pages 适配器允许您将 Qwik City 连接到 Cloudflare Pages.

安装

要集成 cloudflare-pages 适配器，请使用 add 命令

npm run qwik add cloudflare-pages

适配器将在 adapters/ 目录中添加一个新的 vite.config.ts，并创建一个新的入口文件，例如

└── adapters/
    └── cloudflare-pages/
        └── vite.config.ts
└── src/
    └── entry.cloudflare-pages.tsx

此外，在 package.json 中，build.server 和 deploy 脚本将被更新。

请注意您本地环境中的 nodejs 版本，方法是运行 node -v 命令

node -v
v20.11.1

当使用 npm create qwik@latest 设置您的 Qwik 应用程序时，它可能会使用与 Cloudflare Pages 默认使用的 nodejs 版本不同的版本（v16.20.2）。

生产构建

要为生产构建应用程序，请使用 build 命令，此命令将自动运行 npm run build.server 和 npm run build.client

npm run build

在此处阅读完整指南

部署到 Cloudflare Pages

使用 npm run qwik add cloudflare-pages 安装集成后，项目就可以部署到 Cloudflare Pages 了。

如果您的环境中的 nodejs 版本与 Cloudflare Pages（v16.20.2）不同，则需要添加一个 NODE_VERSION 环境变量并将值设置为从您环境中运行 node -v 命令获得的版本

node -v
v20.11.1

要在 Cloudflare 中执行此操作，请转到 **Workers & Pages > YOUR_PROJECT > Settings > Environment variables > Production (and Preview) > Add variables > Save **

有关如何部署网站的更多信息，请参阅 Cloudflare Pages 文档。

请注意，您需要一个 Cloudflare 帐户 才能完成此步骤。

高级

Cloudflare Pages 入口中间件

添加 cloudflare-pages 适配器后，将在 src/entry.cloudflare-pages.tsx 中创建一个新的入口文件。以下是在入口文件中使用内置中间件的示例。

import {
  createQwikCity,
  type PlatformCloudflarePages,
} from '@builder.io/qwik-city/middleware/cloudflare-pages';
import qwikCityPlan from '@qwik-city-plan';
import { manifest } from '@qwik-client-manifest';
import render from './entry.ssr';
 
const fetch = createQwikCity({ render, qwikCityPlan, manifest });
 
export { fetch };

编译后的中间件将在 server/ 目录中构建。此目录还包含一个 _worker.js 文件，该文件根据 Cloudflare Pages 高级模式 实现应用程序的请求处理。该文件只是重新导出了生成的 fetch 处理程序，如下所示。

import { fetch } from "../server/entry.cloudflare-pages";
export default { fetch };

• Cloudflare Pages 中间件源代码
• Cloudflare Pages 高级模式
• 函数调用路由配置

Cloudflare Pages 函数调用路由

Cloudflare Page 的 function-invocation-routes 配置 可用于包含或排除要由工作程序函数使用的特定路径。拥有 _routes.json 文件可以让开发者更细致地控制何时调用您的函数。

这对于确定页面响应应该是服务器端渲染 (SSR) 还是应该使用静态站点生成的 (SSG) index.html 文件很有用。

默认情况下，Cloudflare Pages 适配器不包含 public/_routes.json 配置，而是由 Cloudflare 适配器从构建中自动生成。自动生成的 dist/_routes.json 的示例如下

{
  "include": ["/*"],
  "exclude": [
    "/_headers",
    "/_redirects",
    "/build/*",
    "/favicon.ico",
    "/manifest.json",
    "/service-worker.js",
    "/about"
  ],
  "version": 1
}

在上面的示例中，它表示所有页面都应该进行 SSR。但是，根静态文件（如 /favicon.ico 和 /build/* 中的任何静态资产）应该从函数中排除，而应该作为静态文件处理。

在大多数情况下，生成的 dist/_routes.json 文件是理想的。但是，如果您需要更细致地控制每个路径，则可以提供自己的 public/_routes.json 文件。当项目提供自己的 public/_routes.json 文件时，Cloudflare 适配器将不会自动生成路由配置，而是使用 public 目录中提交的配置。

上下文

您可以在端点方法的 platform 参数中访问 Cloudflare Page 的环境变量

export const onRequest = async ({ platform }) => {
  const secret = platform.env['SUPER_SECRET_TOKEN'];
};

此外，您可以导入 RequestHandler 和 PlatformCloudflarePages 类型，以便在编辑器中获得类型补全。

import { type RequestHandler } from '@builder.io/qwik-city';
import { type PlatformCloudflarePages } from '@builder.io/qwik-city/middleware/cloudflare-pages';
 
export const onGet: RequestHandler<PlatformCloudflarePages> = ({ platform }) => {
  //...
};