静态资源

Workers for Platforms 让您能够大规模部署前端应用程序。通过在 Cloudflare 的全球网络上托管静态资源，您可以在全球范围内提供更快的加载时间，并消除了对外部基础设施的需求。您还可以将这些静态资源与 Cloudflare Workers 中的动态逻辑相结合，为您的客户提供全栈体验。

直接从 Cloudflare 的网络托管并提供 HTML、CSS、JavaScript 和媒体文件，确保全球范围内的快速加载时间。这非常适合博客、登陆页面和文档站点。

将资源托管与 Cloudflare Workers 结合以支持动态、交互式应用程序。使用 Cloudflare KV、D1 和 R2 Storage 存储和检索数据，允许您从单个 Worker 提供前端资源和后端逻辑。

Cloudflare 会自动在世界各地的数据中心缓存静态资源，减少延迟并将世界各地用户的加载时间缩短多达 2 倍。

您的应用程序会自动扩展以处理高流量，而无需您配置或管理基础设施。Cloudflare 会根据需求进行实时动态调整。

将前端资源与服务器端逻辑一起部署，所有这些都在 Cloudflare Workers 内完成。这消除了对单独托管提供商的需求，并确保了简化的部署过程。

作为平台，您代表最终用户上传静态资源是很常见的。这通常是这样的：

1. 您的用户通过您的界面上传文件（HTML、CSS、图像）。
2. 您的平台与 Workers for Platforms API 交互，将静态资源附加到 User Worker 脚本。

一旦您收到用户的静态文件（用于新站点或更新的站点），请完成以下步骤，将文件附加到相应的 User Worker：

1. 创建上传会话 (Upload Session)
2. 上传文件内容
3. 部署/更新 Worker

这些步骤完成后，User Worker 的静态资源将上线在 Cloudflare 的全球网络上。

在发送任何文件数据之前，您需要告诉 Cloudflare 您打算上传哪些文件。该文件列表称为清单（manifest）。清单中的每个项目包括：

• 文件路径（例如，"/index.html" 或 "/assets/logo.png"）
• 表示文件内容的哈希值（32 个十六进制字符）
• 文件大小（以字节为单位）

{
	"/index.html": {
		"hash": "08f1dfda4574284ab3c21666d1ee8c7d4",
		"size": 1234
	},
	"/styles.css": {
		"hash": "36b8be012ee77df5f269b11b975611d3",
		"size": 5678
	}
}

要启动上传过程，请向 Create Assets Upload Session API endpoint 发送 POST 请求。

POST /accounts/{account_id}/workers/dispatch/namespaces/{namespace}/scripts/{script_name}/assets-upload-session

路径参数：

• namespace: Workers for Platforms 分派命名空间的名称
• script_name: 用户 Worker 的名称

在请求正文中，包含一个 JSON 对象，其中列出每个文件路径及其哈希和大小。这有助于 Cloudflare 识别您打算上传的文件，并允许 Cloudflare 检查其中是否已存储任何文件。

curl -X POST \
  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/dispatch/namespaces/$NAMESPACE_NAME/scripts/$SCRIPT_NAME/assets-upload-session" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_TOKEN" \
  --data '{
    "manifest": {
      "/index.html": {
        "hash": "08f1dfda4574284ab3c21666d1ee8c7d4",
        "size": 1234
      },
      "/styles.css": {
        "hash": "36b8be012ee77df5f269b11b975611d3",
        "size": 5678
      }
    }
  }'

您可以计算文件内容的 SHA-256 摘要，然后将其截断或以其他方式一致地表示为 32 个十六进制字符的字符串。请确保每次都以相同的方式进行操作，以便 Cloudflare 可以在上传过程中可靠地匹配文件。

如果所有文件都已存储在 Cloudflare 上，响应将仅返回 JWT 令牌。如果需要新文件或更新文件，响应将返回：

• jwt：一个上传令牌（有效期 1 小时），将用于 API 请求以上传文件内容（第 2 步）。
• buckets：一个文件哈希组数组，指示要一起上传哪些文件。最近上传的文件不会出现在 buckets 中，因为 Cloudflare 已经有了这些文件。

如果上传会话 API 的响应返回 buckets，这意味着您有新文件或已更改的文件需要上传到 Cloudflare。

使用 Workers Assets Upload API 以 base64 编码格式传输任何缺失或更改文件的原始文件字节。上传后，Cloudflare 将存储这些文件，以便以后将它们附加到 User Worker。

与大多数在 Authorization 标头中使用全账户 API 令牌的 Cloudflare API 调用不同，上传文件内容要求使用 assets-upload-session 响应的 jwt 字段中返回的短时效 JWT 令牌。

将其作为 Bearer 令牌包含在标头中：

Authorization: Bearer <upload-session-token>

此令牌有效期为一小时，必须在对 Workers Assets Upload API 的每个上传请求中提供。

您必须将文件作为 multipart/form-data 发送，并使用 base64 编码的内容：

• 字段名称：文件哈希（例如，36b8be012ee77df5f269b11b975611d3）
• 字段值：文件原始字节的 Base64 编码字符串

如果您的 Upload Session 响应列出了一个包含两个文件哈希的 "bucket"：

"buckets": [
  [
    "08f1dfda4574284ab3c21666d1ee8c7d4",
    "36b8be012ee77df5f269b11b975611d3"
  ]
]

您可以在一个请求中上传这两个文件，每个文件作为一个 form-data 字段：

curl -X POST \
  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/assets/upload?base64=true" \
  -H "Authorization: Bearer <upload-session-token>" \
  -F "08f1dfda4574284ab3c21666d1ee8c7d4=<BASE64_OF_INDEX_HTML>" \
  -F "36b8be012ee77df5f269b11b975611d3=<BASE64_OF_STYLES_CSS>"

• <upload-session-token> 是步骤 1 assets-upload-session 响应中的令牌
• <BASE64_OF_INDEX_HTML> 是 index.html 的 Base64 编码内容
• <BASE64_OF_STYLES_CSS> 是 styles.css 的 Base64 编码内容

如果您有多个存储桶（例如，[["hashA"], ["hashB"], ["hashC"]]），您可能需要为每个存储桶重复此过程，每个存储桶组发出一个请求。

清单中的每个文件都已上传后，将返回状态代码 201，并存在 jwt 字段。此 JWT 是一个最终的 "completion"（完成）令牌，可用于通过这组资源来创建 Worker 的部署。此完成令牌有效期为 1 小时。

{
	"success": true,
	"errors": [],
	"messages": [],
	"result": {
		"jwt": "<completion-token>"
	}
}

<completion-token> 表明 Cloudflare 已成功接收并存储了清单指定的文件内容。您将在步骤 3 中使用此 <completion-token> 完成将这些文件附加到 Worker 的操作。

现在 Cloudflare 拥有了所需的所有文件（来自之前的上传步骤），您必须通过向 Upload User Worker API 发出 PUT 请求，将它们附加到 User Worker。这最后一步使用您在上传文件内容后收到的完成令牌，将静态资源链接到 User Worker。

您还可以通过 assets.config 字段指定任何可选设置，以自定义文件的服务方式（例如，处理 HTML 路径中的尾部斜杠）。

curl -X PUT \
  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/dispatch/namespaces/$NAMESPACE_NAME/scripts/$SCRIPT_NAME" \
  -H "Content-Type: multipart/form-data" \
  -H "Authorization: Bearer $API_TOKEN" \
  -F 'metadata={
    "main_module": "index.js",
    "assets": {
      "jwt": "<completion-token>",
      "config": {
        "html_handling": "auto-trailing-slash"
      }
    },
    "compatibility_date": "2025-01-24"
  };type=application/json' \
  -F 'index.js=@/path/to/index.js;type=application/javascript'

• "jwt": "<completion-token>" 将新上传的文件链接到 Worker
• 包含 "html_handling"（或 "config" 下的其他字段）是可选的，可以自定义静态文件的服务方式
• 如果用户的 Worker 代码未更改，则可以省略代码文件或重新上传相同的 index.js

一旦此 PUT 请求成功，就会在 User Worker 上提供文件。路由到该 Worker 的请求将提供新的或更新的静态资源。

如果您更喜欢基于 CLI 的方法并且您的平台设置允许直接发布，您可以使用 Wrangler 部署 Worker 代码和静态资源。Wrangler 打包并上传静态资源（从指定的目录）和您的 Worker 脚本，因此您可以在一处管理所有内容。

创建或更新您的 Wrangler 配置文件，以指定 Wrangler 应在哪里查找静态文件：

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-static-site",
	"main": "./src/index.js",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"assets": {
		"directory": "./public",
		"binding": "ASSETS",
	},
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-static-site"
main = "./src/index.js"
# Set this to today's date
compatibility_date = "2026-08-17"

[assets]
directory = "./public"
binding = "ASSETS"

• directory：包含您的静态文件的本地文件夹（例如，./public）。
• binding：用于在 Worker 代码中引用这些资源的绑定名称。

将静态文件（HTML、CSS、图像等）放在指定目录中（在本例中为 ./public）。在您发布 Worker 时，Wrangler 会自动检测并打包这些文件。

如果您需要在 Worker 脚本中引用这些文件以动态地提供它们，可以使用 ASSETS 绑定，如下所示：

export default {
	async fetch(request, env, ctx) {
		return env.ASSETS.fetch(request);
	},
};

运行 Wrangler 来发布您的 Worker 代码和静态资源：

npx wrangler deploy --name <USER_WORKER_NAME> --dispatch-namespace <NAMESPACE_NAME>

Wrangler 将自动检测您的静态文件，对它们进行打包，并与您的 Worker 代码一起上传到 Cloudflare。