跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

已知问题

最后更新 查看 MarkdownAgent 设置

以下是 Cloudflare Pages 的一些已知 bug 和问题:

构建和部署

  • GitHub 和 GitLab 目前是自动 CI/CD 构建唯一支持的平台。Direct Upload 允许你集成自己的构建平台或从本地计算机上传。

  • Cloudflare Pages 目前不支持增量构建。

  • 通过仪表板的 Direct Upload 选项上传 /functions 目录不起作用(请参阅 在 Direct Upload 中使用 Functions)。

  • 来自 fork 仓库的提交/PR 不会创建预览。未来会支持此功能。

Git 配置

  • 若使用 Git 集成部署,之后无法切换到 Direct Upload。但是,若你已使用 Git 集成项目且不想在每次推送提交时触发部署,可以禁用/暂停自动部署。或者,你可以删除 Pages 项目并创建指向不同仓库的新项目以进行更新。

构建配置

  • *.pages.dev 子域名目前无法更改。若需要更改 *.pages.dev 子域名,请删除项目并创建新项目。

  • Hugo 构建自动运行旧版本。要运行最新版本的 Hugo(例如 0.101.0),需要设置环境变量。将 HUGO_VERSION 设为 0.101.0 或你选择的 Hugo 版本。

  • 默认情况下,Cloudflare 在 Pages 构建环境中使用 Node 12.18.0。若需要使用较新的 Node 版本,请参阅构建配置页面了解配置选项。

  • 对于从 Netlify 迁移的用户,Cloudflare 不支持 Netlify 的 Forms 功能。Pages Functions 可用作 Netlify Serverless Functions 的等效方案。

自定义域名

  • 目前无法添加具有以下特征的自定义域名:

    • 通配符,例如 *.domain.com。
    • 该域名上已路由 Worker。
  • 目前无法在该域名已启用 Cloudflare Access 策略的情况下添加自定义域名。

  • Cloudflare 的 Load Balancer 不适用于 *.pages.dev 项目;将出现 Error 1000: DNS points to prohibited IP。

  • 添加自定义域名时,若 Cloudflare 无法验证该主机名上的 SSL 证书请求,域名将不会验证。为使 SSL 验证成功,确保 Cloudflare Access 或 Cloudflare Worker 允许对验证路径的请求:http://{domain_name}/.well-known/acme-challenge/*。

  • 由于 Cloudflare for SaaS 的证书优先级,Advanced Certificates 无法与 Cloudflare Pages 一起使用。

Pages Functions

  • Functions 目前不支持添加/移除 polyfill,因此打包器(例如 webpack)可能无法运行。

  • Advanced Mode Pages Functions(使用 _worker.js 文件的 Pages Functions)目前不可用 passThroughOnException()。

  • passThroughOnException() 目前不如 Workers 中那样 resilient。我们目前将 Pages Functions 代码包装在 try...catch ↗ 块中并回退到调用 env.ASSETS.fetch()。这意味着任何严重故障(例如超出 CPU 时间或内存)仍可能抛出错误。

在 *.pages.dev 域名上启用 Access

若要为预览部署和 *.pages.dev 域名启用 Cloudflare Access ↗,必须:

  1. 在 Cloudflare 仪表板中,前往 Workers & Pages 页面。

    前往 Workers & Pages ↗
  2. 选择你的 Pages 项目。

  3. 前往 Settings(设置) > Enable access policy(启用访问策略)。

  4. 在为预览部署创建的 Access 策略上选择 Manage(管理)。

  5. 在 Access > Applications(应用程序) 下,选择你的项目。

  6. 选择 Configure(配置)。

  7. 在 Public hostname(公共主机名) 下,在 Subdomain(子域名) 字段中删除通配符(*)并选择 Save(保存)。此步骤可能需要更改 Application name(应用程序名称) 以避免错误。

此时,你的 *.pages.dev 域名已在 Access 后面得到保护。要重新保护预览部署:

  1. 返回 Pages 项目 > Settings(设置) > General(常规),并重新选择 Enable access policy(启用访问策略)。
  2. 确认已创建两个 Access 策略,一个用于 *.pages.dev 域名,一个用于预览部署(*.<YOUR_SITE>.pages.dev)。

若有自定义域名并将 *.pages.dev 域名保护在 Access 后面,必须:

  1. 在 Cloudflare 仪表板 ↗中,前往 Zero Trust > Access controls(访问控制) > Applications(应用程序)。选择 Create new application(创建新应用程序) > Self-hosted and private(自托管和私有)。
  2. 选择 Add public hostname(添加公共主机名),从 Domain 下拉菜单中选择自定义域名。
  3. 配置访问规则以定义谁可以访问 Access 身份验证页面。
  4. 选择 Create(创建)。

如果你遇到未列出的问题,请在 Cloudflare Workers Discord 中告知团队。在 discord.cloudflare.com ↗ 获取邀请,并在 #pages-general 频道分享 bug 报告。

删除部署数量较多的项目

若 Pages 项目部署数量较多(超过 100 个),可能无法删除。Cloudflare 团队正在跟踪此问题。

作为解决方法,可以使用 wrangler pages deployment delete 单独删除部署。删除部署后,即可删除 Pages 项目。

npx wrangler pages deployment delete <DEPLOYMENT_ID> --project-name <PROJECT_NAME>

使用 --force 标志跳过确认提示并强制删除别名部署。

要删除特定项目的 所有 预览部署,请保存并运行以下脚本之一,并将项目名称作为第一个参数传入。每个脚本都会找到并保留生产部署,然后并行删除其余预览部署。您可以选择传入第二个参数,以控制同时执行的删除数量(默认值为 5):

#!/usr/bin/env bash
set -euo pipefail

project="${1:?usage: $0 <project-name> [parallelism]}"
parallel="${2:-5}"

deployments=$(npx --no-install wrangler pages deployment list \
    --project-name "$project" --json)

prod_id=$(jq -r '[.[] | select(.Environment == "Production")][0].Id // empty' <<<"$deployments")
if [ -z "$prod_id" ]; then
    echo "No production deployment found for '$project' - aborting." >&2
    echo "This script keeps your production deployment, so it needs one to run." >&2
    echo "Create a production deployment by deploying to your production branch (for example: npx wrangler pages deploy <output-dir> --project-name $project), then re-run this script." >&2
    exit 1
fi

to_delete=$(jq -r '.[] | select(.Environment != "Production") | .Id' <<<"$deployments")
count=$(printf '%s\n' "$to_delete" | grep -c . || true)

if [ "$count" -eq 0 ]; then
    echo "Nothing to delete. Production: $prod_id"
    exit 0
fi

echo "Production: $prod_id. Deleting $count preview deployments..."

failed=$(printf '%s\n' "$to_delete" | xargs -n1 -P "$parallel" -I{} \
    sh -c 'npx --no-install wrangler pages deployment delete "$1" --project-name "$2" --force >/dev/null 2>&1 \
           || echo "$1"' _ {} "$project")

if [ -n "$failed" ]; then
    echo "The following deployments failed to delete:" >&2
    printf '%s\n' "$failed" >&2
    exit 1
fi

echo "Done."
param(
    [Parameter(Mandatory=$true)][string]$ProjectName,
    [int]$Throttle = 5
)

$ErrorActionPreference = "Stop"
$env:CLOUDFLARE_ACCOUNT_ID = $env:CLOUDFLARE_ACCOUNT_ID  # ensure inherited into runspaces

$deployments = npx --no-install wrangler pages deployment list `
    --project-name $ProjectName --json | ConvertFrom-Json

$prod = $deployments | Where-Object { $_.Environment -eq "Production" } | Select-Object -First 1
if (-not $prod) {
    throw "No production deployment found for '$ProjectName' - aborting to avoid data loss. This script keeps your production deployment, so it needs one to run. Create a production deployment by deploying to your production branch (for example: npx wrangler pages deploy <output-dir> --project-name $ProjectName), then re-run this script."
}

$toDelete = $deployments | Where-Object { $_.Environment -ne "Production" }

if ($toDelete.Count -eq 0) {
    Write-Output "Nothing to delete. Production: $($prod.Id)"
    return
}

Write-Output "Production: $($prod.Id). Deleting $($toDelete.Count) preview deployments..."

$results = $toDelete | ForEach-Object -Parallel {
    $id = $_.Id
    npx --no-install wrangler pages deployment delete $id `
        --project-name $using:ProjectName --force *> $null
    [pscustomobject]@{ Id = $id; ExitCode = $LASTEXITCODE }
} -ThrottleLimit $Throttle

$failed = $results | Where-Object { $_.ExitCode -ne 0 }
if ($failed) {
    Write-Warning "$($failed.Count) deletions failed:"
    $failed | Format-Table -AutoSize
    exit 1
}

Write-Output "Done."

如果存在活动的生产部署,这些脚本不会将其删除。

在 Cloudflare Load Balancer 中将 Pages 用作源站

Cloudflare Load Balancing 未设置 host 标头将无法工作。要将 Pages 项目用作目标,在创建池时确保选择 Add host header(添加主机标头),并将 host 标头值和端点地址都设置为 pages.dev 域名。

请参阅将 Cloudflare Pages 用作源站获取完整教程。

这篇文档对您有帮助吗?