可将静态资产（HTML、CSS、图片及其他文件）作为 Worker 的一部分上传，Cloudflare 负责缓存并向 Web 浏览器提供。
从 CLI 开始 — 搭建带 API Worker 的 React SPA，并使用 Cloudflare Vite 插件。
npm create cloudflare@latest -- my-react-app --framework=reactyarn create cloudflare my-react-app --framework=reactpnpm create cloudflare@latest my-react-app --framework=react或直接部署到 Cloudflare
了解更多 Workers 支持的框架。
支持的框架
部署项目时，Cloudflare 会在一次操作中同时部署 Worker 代码和静态资产。该部署在 Cloudflare 网络上作为紧密集成的「单元」运行，结合静态文件托管、自定义逻辑与全球缓存。
Wrangler 配置文件中指定的 assets 目录是这一设计的核心。部署期间，Wrangler 会自动将该目录中的文件上传到 Cloudflare 基础设施。部署后，对这些资产的请求会高效路由到离用户最近的位置。
{
"$schema": "./node_modules/wrangler/config-schema.json",
"name": "my-spa",
"main": "src/index.js",
// Set this to today's date
"compatibility_date": "2026-08-17",
"assets": {
"directory": "./dist",
"binding": "ASSETS"
}
}"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-spa"
main = "src/index.js"
# Set this to today's date
compatibility_date = "2026-08-17"
[assets]
directory = "./dist"
binding = "ASSETS"通过添加 assets 绑定（binding），可在 Worker 代码内直接获取并提供资产。
// index.js
export default {
async fetch(request, env) {
const url = new URL(request.url);
if (url.pathname.startsWith("/api/")) {
return new Response(JSON.stringify({ name: "Cloudflare" }), {
headers: { "Content-Type": "application/json" },
});
}
return env.ASSETS.fetch(request);
},
};from workers import WorkerEntrypoint, Response
from urllib.parse import urlparse
class Default(WorkerEntrypoint):
async def fetch(self, request):
# Example of serving static assets
url = urlparse(request.url)
if url.path.startswith("/api/):
return Response.json({"name": "Cloudflare"})
return await self.env.ASSETS.fetch(request)默认情况下，若请求的 URL 匹配静态资产目录中的文件，将直接提供该文件——不会调用 Worker 代码。若未找到匹配资产且存在 Worker 脚本，请求将由 Worker 处理。Worker 可返回响应，或使用资产绑定（binding）（例如 env.ASSETS.fetch(request)）再次交给静态资产。若无 Worker 脚本，则返回 404 Not Found。
可通过在 Wrangler 配置文件的 assets 下设置 not_found_handling 选项更改未匹配静态资产时的默认行为：
not_found_handling = "single-page-application"：对未匹配静态资产的请求返回带index.html的200 OK。适用于单页应用（SPA）。建议与选择性路由run_worker_first配合以实现高级路由控制。not_found_handling = "404-page"：对未匹配静态资产的请求返回带最近404.html的404 Not Found。
{
"assets": {
"directory": "./dist",
"not_found_handling": "single-page-application"
}
}[assets]
directory = "./dist"
not_found_handling = "single-page-application"若希望在提供资产之前执行 Worker 代码，可使用 run_worker_first 选项。设为 true 会对所有请求调用 Worker 脚本，或配置为路由模式数组以实现选择性 Worker 优先路由：
在特定路径上调用 Worker 脚本：
{
"name": "my-spa-worker",
// Set this to today's date
"compatibility_date": "2026-08-17",
"main": "./src/index.ts",
"assets": {
"directory": "./dist/",
"not_found_handling": "single-page-application",
"binding": "ASSETS",
"run_worker_first": ["/api/*", "!/api/docs/*"]
}
}name = "my-spa-worker"
# Set this to today's date
compatibility_date = "2026-08-17"
main = "./src/index.ts"
[assets]
directory = "./dist/"
not_found_handling = "single-page-application"
binding = "ASSETS"
run_worker_first = [ "/api/*", "!/api/docs/*" ]更高级的模式请参阅带引导数据的 SPA shell，其中使用 HTMLRewriter 将预取的 API 数据注入 HTML 流。
路由选项
Cloudflare 为其网络中的静态资产提供自动缓存，确保全球用户快速获取。请求静态资产时，会自动缓存以供后续请求使用。
-
首次请求： 首次请求资产时，从存储获取并在最近的 Cloudflare 位置缓存。
-
后续请求： 若对同一资产的请求到达未缓存该资产的数据中心，Cloudflare 的分层缓存系统可从附近缓存检索，而无需回到存储。这提高缓存命中率、降低延迟并减少不必要的源站获取。