为 Worker 配置资产需要指定目录，并在 Worker 的 Wrangler 文件中可选配置资产绑定（binding）。资产绑定（binding）允许在 Worker 脚本内动态获取资产（例如 env.ASSETS.fetch()），类似于通过 Service binding 发起 fetch() 调用。
每个 Worker 只能配置一组静态资产。
要提供的静态资产文件夹。对许多框架而言，这是 ./public/、./dist/ 或 ./build/ 文件夹。
{
"$schema": "./node_modules/wrangler/config-schema.json",
"name": "my-worker",
// Set this to today's date
"compatibility_date": "2026-08-17",
"assets": {
"directory": "./public/",
},
}"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker"
# Set this to today's date
compatibility_date = "2026-08-17"
[assets]
directory = "./public/"有时资产目录中存在不应上传的文件。
此时，在资产目录根目录创建 .assetsignore 文件。
该文件格式与 .gitignore 相同。
Wrangler 不会上传与此文件中行匹配的资产文件。
示例
你正在从 Pages 项目迁移，资产目录为 dist。
你不希望将服务端 Worker 代码或 Pages 配置文件作为公共客户端资产上传。
添加以下 .assetsignore 文件：
_worker.js
_redirects
_headers部署 Worker 时，Wrangler 将不再把这些文件作为客户端资产上传。
控制是否在原本会匹配资产的请求上仍调用 Worker 脚本。run_worker_first = false（默认）会提供匹配请求的任何静态资产，而 run_worker_first = true 会无条件调用 Worker 脚本。
{
"$schema": "./node_modules/wrangler/config-schema.json",
"name": "my-worker",
// Set this to today's date
"compatibility_date": "2026-08-17",
"main": "src/index.ts",
// The following configuration unconditionally invokes the Worker script at
// `src/index.ts`, which can programmatically fetch assets via the ASSETS binding
"assets": {
"directory": "./public/",
"binding": "ASSETS",
"run_worker_first": true,
},
}"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker"
# Set this to today's date
compatibility_date = "2026-08-17"
main = "src/index.ts"
[assets]
directory = "./public/"
binding = "ASSETS"
run_worker_first = true也可将 run_worker_first 指定为路由模式数组，仅对特定路由优先运行 Worker 脚本。
数组支持使用 * 进行深度匹配的 glob 模式，以及以 ! 为前缀的否定模式。
否定模式优先于非否定模式。当非否定模式匹配且没有任何否定模式匹配时，Worker 将优先运行。
模式列出顺序无意义。
run_worker_first 常与 not_found_handling = "single-page-application" 设置 配合使用：
{
"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/*" ]在此配置中，对 /api/* 路由的请求将优先调用 Worker 脚本；/api/docs/* 除外，其遵循默认的资产优先路由行为。
run_worker_first 的常见用途包括身份验证检查、A/B 测试，以及向 SPA shell 注入引导数据。
配置可选绑定（binding）后，可在 Worker 脚本内访问资产集合。
{
"$schema": "./node_modules/wrangler/config-schema.json",
"name": "my-worker",
"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-worker"
main = "./src/index.js"
# Set this to today's date
compatibility_date = "2026-08-17"
[assets]
directory = "./public/"
binding = "ASSETS"在上例中，可通过 env.ASSETS 访问资产。
参数
request: Request | URL | string传入 Request 对象、URL 对象或 URL 字符串。通过此方法发起的请求会应用html_handling和not_found_handling配置。
响应
Promise<Response>返回给定请求的静态资产响应。
示例
动态代码可使用资产绑定新建请求，或将传入请求转发到项目的静态资产，例如 env.ASSETS.fetch(request)、env.ASSETS.fetch(new URL('https://assets.local/my-file')) 或 env.ASSETS.fetch('https://assets.local/my-file')。URL 中使用的主机名（例如 assets.local）无实际意义——任意有效主机名均可。仅 URL 路径用于匹配资产。
以下示例将 Worker 脚本配置为对所有指向 /api/ 的请求返回响应；否则 Worker 脚本会将传入请求传递给资产绑定。由于 Worker 脚本仅在请求路由未匹配任何静态资产时调用，此情况始终会评估 not_found_handling 行为。
export default {
async fetch(request, env) {
const url = new URL(request.url);
if (url.pathname.startsWith("/api/")) {
// TODO: Add your custom /api/* logic here.
return new Response("Ok");
}
// Passes the incoming request through to the assets binding.
// No asset matched this request, so this will evaluate `not_found_handling` behavior.
return env.ASSETS.fetch(request);
},
};interface Env {
ASSETS: Fetcher;
}
export default {
async fetch(request, env): Promise<Response> {
const url = new URL(request.url);
if (url.pathname.startsWith("/api/")) {
// TODO: Add your custom /api/* logic here.
return new Response("Ok");
}
// Passes the incoming request through to the assets binding.
// No asset matched this request, so this will evaluate `not_found_handling` behavior.
return env.ASSETS.fetch(request);
},
} satisfies ExportedHandler<Env>;有关各类静态资产路由配置选项，请参阅路由。
Smart Placement 可将 Worker 代码部署在靠近后端基础设施的位置。仅当指定指向 Worker 代码的 main 时，Smart Placement 才会生效。
若通过设置 run_worker_first=true 希望在资产之前运行 Worker 代码，所有请求须先到达 Smart Placement 后的 Worker。因此，资产请求可能出现延迟增加。
在需要与其他后端服务集成、在提供任何资产之前验证请求，或希望在提供资产前修改资产时，可将 Smart Placement 与 run_worker_first=true 配合使用。
若希望部分资产尽可能快速提供给用户，而其他资产在 smart-placed Worker 之后提供，可考虑将应用拆分为多个 Worker，并使用 service bindings 连接它们。
启用 Smart Placement 且 run_worker_first=false（或未指定）时，可从尽可能靠近用户的位置提供资产，同时将 Worker 逻辑移至最高效的位置运行（例如靠近数据库）。
在优先快速交付资产时，可将 Smart Placement 与 run_worker_first=false（或未指定）配合使用。
这不会影响默认路由行为。