# @cloudflare/kv-asset-handler 中文文档 规范地址：https://npmcn.com/package/%40cloudflare/kv-asset-handler/ 版本：0\.5\.0 npm 元数据更新时间：2026-09-18T16:12:37.896Z 中文译文更新时间：2026-11-10T02:56:29.835Z 软件包许可：MIT OR Apache-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40cloudflare/kv-asset-handler 原文对照：https://npmcn.com/package/%40cloudflare/kv-asset-handler/?lang=original 项目主页：https://github.com/cloudflare/workers-sdk#readme 源码仓库：https://github.com/cloudflare/workers-sdk ## 关键信息（来自 npm 元数据） - 包体积（解压后）：183 kB，8 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - Node.js 要求：\>=22\.0\.0 - 运行依赖：0 个 - 首次发布：2019-09-19T23:45:00.441Z - 最新版本发布：2026-04-30T16:58:56.693Z - 近 30 天下载量：124564202（2026-10-10 至 2026-11-08，npm 官方下载统计） - 已发布版本数：26（近 12 个月 3 个） ## 中文简介 KV 资产路线请求 ## 安装 ```sh npm install @cloudflare/kv-asset-handler ``` 也可以使用：`pnpm add @cloudflare/kv-asset-handler`、`yarn add @cloudflare/kv-asset-handler`、`bun add @cloudflare/kv-asset-handler` ## README # @cloudflare/kv-asset-handler 页面存档备份,存于互联网档案馆 [![npm](https://img.shields.io/npm/v/@cloudflare/kv-asset-handler.svg)](https://www.npmjs.com/package/@cloudflare/kv-asset-handler)   [![Run npm tests](https://github.com/cloudflare/kv-asset-handler/actions/workflows/test.yml/badge.svg)](https://github.com/cloudflare/kv-asset-handler/actions/workflows/test.yml)   [![Lint Markdown](https://github.com/cloudflare/kv-asset-handler/actions/workflows/lint.yml/badge.svg)](https://github.com/cloudflare/kv-asset-handler/actions/workflows/lint.yml)   `kv-asset-handler` 一个开源库,用于管理从 [工人 KV](https://developers.cloudflare.com/workers/runtime-apis/kv) 内置 [云花岗工人](https://workers.dev/) 函数. `kv-asset-handler` 设计用于: [工人工地](https://developers.cloudflare.com/workers/platform/sites),包含在 [响尾蛇](https://github.com/cloudflare/wrangler)我们部署工人项目的指挥线工具. `kv-asset-handler` 运行为 Cloudflare 函数的一部分,因此您可以自定义 _怎么样_ 财务报告和审定财务报表 _何时_ 您的静态资产被装入, 以及定制 这些资产如何行为 在他们发送到客户之前. 大多数用户和网站不需要这些定制,只想为其静态构建的应用程序服务. 简单的用例,你可以检查出来 [云旗页](https://pages.cloudflare.com/)我们的电池包括了在Cloudflare的边缘网络上部署静态站点的方法。 工人站点被设计为Cloudflare Pages的前身,所以检查Pages,如果你只是想部署你的静态站点而不需要任何特殊的定制! 用户 _对_ 想要定制他们的资产, 想要在他们的静态资产之上积累复杂的经验, `kv-asset-handler` (和默认) [工人工地模板](https://github.com/cloudflare/worker-sites-template),它规定与 Wrangler + Workers Sites 一起使用)允许您自定义缓存行为,头条,以及其它任何关于您的工人如何为存储在Workers KV的站点装入静态资产. Cloudflare工人Discord服务器是工人用户获得帮助,分享反馈,合作改善我们的平台的活跃地. 这个 `#workers` 特别频道是聊天的好地方 `kv-asset-handler`,并为用户使用这些工具建立酷酷的经验! 如果你有问题,想分享你的工作, 或者提供反馈, [和我们一起Discord打个招呼](https://discord.cloudflare.com/)来啊! - [安装](https://npmcn.com/package/%40cloudflare/kv-asset-handler/#readme-installation) - [使用量](https://npmcn.com/package/%40cloudflare/kv-asset-handler/#readme-usage) - [`getAssetFromKV`](https://npmcn.com/package/%40cloudflare/kv-asset-handler/#readme-getassetfromkv) - [示例](https://npmcn.com/package/%40cloudflare/kv-asset-handler/#readme-example) - [返回时](https://npmcn.com/package/%40cloudflare/kv-asset-handler/#readme-return) - [可选参数](https://npmcn.com/package/%40cloudflare/kv-asset-handler/#readme-optional-arguments) - [`mapRequestToAsset`](https://npmcn.com/package/%40cloudflare/kv-asset-handler/#readme-maprequesttoasset) - [示例](https://npmcn.com/package/%40cloudflare/kv-asset-handler/#readme-example-1) - [`cacheControl`](https://npmcn.com/package/%40cloudflare/kv-asset-handler/#readme-cachecontrol) - [`browserTTL`](https://npmcn.com/package/%40cloudflare/kv-asset-handler/#readme-browserttl) - [`edgeTTL`](https://npmcn.com/package/%40cloudflare/kv-asset-handler/#readme-edgettl) - [`bypassCache`](https://npmcn.com/package/%40cloudflare/kv-asset-handler/#readme-bypasscache) - [`ASSET_NAMESPACE` (ES模块所需)](https://npmcn.com/package/%40cloudflare/kv-asset-handler/#readme-asset_namespace-required-for-es-modules) - [`ASSET_MANIFEST` (ES模块所需)](https://npmcn.com/package/%40cloudflare/kv-asset-handler/#readme-asset_manifest-required-for-es-modules) - [`defaultETag`](https://npmcn.com/package/%40cloudflare/kv-asset-handler/#readme-defaultetag-optional) - [辅助功能](https://npmcn.com/package/%40cloudflare/kv-asset-handler/#readme-helper-functions) - [`mapRequestToAsset`](https://npmcn.com/package/%40cloudflare/kv-asset-handler/#readme-maprequesttoasset-1) - [`serveSinglePageApp`](https://npmcn.com/package/%40cloudflare/kv-asset-handler/#readme-servesinglepageapp) - [缓存重新验证和标签](https://npmcn.com/package/%40cloudflare/kv-asset-handler/#readme-cache-revalidation-and-etags) ## 安装 将此软件包添加到您的 `package.json` 在您的根中运行此选项 项目目录 : ``` npm i @cloudflare/kv-asset-handler ``` ## 使用量 这个软件包的设计是为了与 [工人场地](https://workers.cloudflare.com/sites)。 。 。 . ## `getAssetFromKV` 获取 Asset from KV( Evt) QQ 答应 `getAssetFromKV` 是需要一个 `Evt` 对象( 包含 a `Request` (单位:千美元) [`waitUntil`](https://developers.cloudflare.com/workers/runtime-apis/fetch-event#waituntil)返回 a `Response` 如果请求与 KV 中的资产相匹配, 则对象将丢出 `KVError`。 。 。 . #### 示例 此示例检查 KV 中存在一个值, 如果存在则返回, 如果存在, 则返回 404 。 它也服务于Index.html from `/`。 。 。 . ### 返回时 `getAssetFromKV` 返回 a `Promise` 与 `Response` 是请求的资产主体. 已知要抛出的错误有: - 方法不完全错误 - 非 Found 错误 - 内部错误 #### ES 模块 ```js import manifestJSON from "__STATIC_CONTENT_MANIFEST"; import { getAssetFromKV, MethodNotAllowedError, NotFoundError, } from "@cloudflare/kv-asset-handler"; const assetManifest = JSON.parse(manifestJSON); export default { async fetch(request, env, ctx) { if (request.url.includes("/docs")) { try { return await getAssetFromKV( { request, waitUntil(promise) { return ctx.waitUntil(promise); }, }, { ASSET_NAMESPACE: env.__STATIC_CONTENT, ASSET_MANIFEST: assetManifest, } ); } catch (e) { if (e instanceof NotFoundError) { // ... } else if (e instanceof MethodNotAllowedError) { // ... } else { return new Response("An unexpected error occurred", { status: 500 }); } } } else return fetch(request); }, }; ``` #### 服务工作者 ```js import { getAssetFromKV, MethodNotAllowedError, NotFoundError, } from "@cloudflare/kv-asset-handler"; addEventListener("fetch", (event) => { event.respondWith(handleEvent(event)); }); async function handleEvent(event) { if (event.request.url.includes("/docs")) { try { return await getAssetFromKV(event); } catch (e) { if (e instanceof NotFoundError) { // ... } else if (e instanceof MethodNotAllowedError) { // ... } else { return new Response("An unexpected error occurred", { status: 500 }); } } } else return fetch(event.request); } ``` ### 可选参数 您可以自定义行为 `getAssetFromKV` ,将以下属性作为对象传递到第二个参数中. ``` getAssetFromKV(event, { mapRequestToAsset: ... }) ``` #### `mapRequestToAsset` 地图请求 请求 将请求映射到 Cloudflare 的 KV 中查找的值 默认情况下, 映射请求ToAsset 设置为导出函数 [`mapRequestToAsset`](https://npmcn.com/package/%40cloudflare/kv-asset-handler/#readme-maprequesttoasset-1)。这适用于大多数静态站点生成器,但您可以通过将自己的功能传递为 `mapRequestToAsset`。该职能应当包括: `Request` 对象作为其唯一的参数,并返回新参数 `Request` 对象,在资产表/ KV 中查找更新路径. 用于 SPA 绘图 [`serveSinglePageApp`](https://npmcn.com/package/%40cloudflare/kv-asset-handler/#readme-servesinglepageapp) 函数 #### 示例 脱 `/docs` 在Cloudflare的KV中查找资产之前. ```js import { getAssetFromKV, mapRequestToAsset } from '@cloudflare/kv-asset-handler' ... const customKeyModifier = request => { let url = request.url //custom key mapping optional url = url.replace('/docs', '').replace(/^\/+/, '') return mapRequestToAsset(new Request(url, request)) } let asset = await getAssetFromKV(event, { mapRequestToAsset: customKeyModifier }) ``` #### `cacheControl` 类型:对象 `cacheControl` 允许您为您工作人访问的 Cloudflare 缓存配置选项,也可以为您工作人的回复同时发送浏览器缓存头。 默认值如下: ```javascript let cacheControl = { browserTTL: null, // do not set cache control ttl on responses edgeTTL: 2 * 60 * 60 * 24, // 2 days bypassCache: false, // do not bypass Cloudflare's cache }; ``` ##### `browserTTL` 类型: 数字 qq 无效 无效: 真 设置 `Cache-Control: max-age` 回复信头从工人返回。 默认设置为 `null` 完全不会添加标题. ##### `edgeTTL` 类型: 数字 qq 无效 无效: 真 设置 `Cache-Control: max-age` 用作边缘缓存密钥的响应上的标题 。 默认设定为2天`2 * 60 * 60 * 24`) (中文(简体) ). 当空将完全不缓存在边缘时 . ##### `bypassCache` 类型:布尔 确定是否在 Cloudflare 的边缘缓存中缓存请求 。 默认设置为 `false` (为生产建设推荐. 当需要消除缓存对测试的影响时,对开发有用. #### `ASSET_NAMESPACE` (ES模块所需) 类型: KV 命名空间绑定 KV Namespace 的绑定名称, 包含要服务的文件的密钥/ 值项 。 默认情况下,工人工地使用a [对工人 KV 命名空间具有约束力](https://developers.cloudflare.com/workers/reference/storage/api/#namespaces) 名称 `__STATIC_CONTENT`。 。 。 . 进一步假设,这个命名空间由静态资产组成,如HTML,CSS,JavaScript,或图像文件,从一个相对路径中键入,该路径大致匹配了所请求的所假设的URL路径名. 在ES模块格式中,需要这个参数,并且可以从 `env`。 。 。 . ##### ES 模块 ```js return getAssetFromKV( { request, waitUntil(promise) { return ctx.waitUntil(promise); }, }, { ASSET_NAMESPACE: env.__STATIC_CONTENT, } ); ``` ##### 服务工作者 ``` return getAssetFromKV(event, { ASSET_NAMESPACE: MY_NAMESPACE }) ``` #### `ASSET_MANIFEST` (ES模块所需) 类型:文本blob(JSON格式化)或对象 向 Cloudflare 存储的密钥绘制请求的文件路径 . Wrangler Workers Witchs 将一个文本blob捆绑起来,将Wrangler作为缓存-busing度量生成的内容-hashed密钥的路径绘制成地图. 如果此选项/ 绑定不存在, 函数会回落到使用原始路径名查找您在 KV 中的资产 。 如果无论出于何种原因,您已经滚动了您自己的执行, 您可以通过一个字符串化的 JSON 对象, 将您自己的执行包含在 KV 命名空间中 . 在ES模块格式中,需要这个参数,可以导入. ##### ES 模块 ```js import manifestJSON from "__STATIC_CONTENT_MANIFEST"; let manifest = JSON.parse(manifestJSON); manifest["index.html"] = "index.special.html"; return getAssetFromKV( { request, waitUntil(promise) { return ctx.waitUntil(promise); }, }, { ASSET_MANIFEST: manifest, // ... } ); ``` ##### 服务工作者 ``` let assetManifest = { "index.html": "index.special.html" } return getAssetFromKV(event, { ASSET_MANIFEST: assetManifest }) ``` #### `defaultMimeType` (可选) 类型:字符串 这是用于未识别或缺失扩展名的文件的 MIME 类型 。 默认值为 `'text/plain'`。 。 。 . 如果您正在服务一个静态站点, 并且希望使用无扩展的 HTML 文件而不是 index.html 文件, 请设定为 `'text/html'`。 。 。 . #### `defaultDocument` (可选) 类型:字符串 这是用于请求的默认文档 `'/'` 或没有有效的 mime 类型 `'/about'` 或者说 `'/about.me'`。默认值是 `'index.html'`。 。 。 . #### `defaultETag` (可选) 类型 : `'strong' | 'weak'` 这决定了响应的格式 [ETag 页眉](https://developer.mozilla.org/docs/Web/HTTP/Headers/ETag)。如果资源在缓存中,在返回之前,ETag总是被削弱. 默认值为 `'strong'`。 。 。 . # 辅助功能 ## `mapRequestToAsset` 地图请求 请求 Cloudflare KV 中用于映射密钥来源请求的默认函数 . 选择任何结束于 `/` 或评价到 HTML 文件及附件 `index.html` 或者说 `/index.html` 在您的 KV 命名空间中查找 . ## `serveSinglePageApp` 服务 SinglePageApp( 请求) 请求 用于将请求映射到单一根的自定义处理器 : `index.html`. 最常见的使用案例是单页应用程序 - 有应用中路由的框架 - 如React Router,VueJS等. 这需要零辩论. ```js import { getAssetFromKV, serveSinglePageApp } from '@cloudflare/kv-asset-handler' ... let asset = await getAssetFromKV(event, { mapRequestToAsset: serveSinglePageApp }) ``` # 缓存重新验证和标签 所有答复都来自缓存(包括来自 `cf-cache-status: MISS`包括: `etag` 用于识别资源版本的响应头。 这个 `etag` 值与 `ASSET_MANIFEST`。每次资产变化时都会更新它,这样看起来: `etag: ..` (预算外). `etag: index.54321.html`) (中文(简体) ). 资源用于 `etag` 允许浏览器使用 `if-none-match` 请求未来对该资源提出有条件的请求。 这有两个主要好处: - 当一个请求 `if-none-match` 值与 `etag` cloudflare 缓存中的资源 `304 Not Modified` 没有身体的响应,节省带宽. - 对服务器上文件的更改立即在浏览器中反映 - 即使缓存控制指令 `max-age` 未过期. #### 禁用 `etag` 转身 `etags` **关**,您必须绕过缓存 : ```js /* Turn etags off */ let cacheControl = { bypassCache: true, }; ``` #### 语法和比较上下文 `kv-asset-handler` 设置并评价 [强验证符](https://developer.mozilla.org/en-US/docs/Web/HTTP/Conditional_requests#Strong_validation)保留 `etag` 完整性,数值的格式偏离 [RFC2616 建议: `etag` 有引号](https://tools.ietf.org/html/rfc2616#section-3.11)这是故意的。 Cloudflare 缓存应用 `W/` 全部前缀 `etags` 引用字符串 -- -- 一个转换 `etag` 给客户端的"弱验证器". ## 常见问题 ### @cloudflare/kv-asset-handler 是什么？ KV 资产路线请求 ### 如何安装 @cloudflare/kv-asset-handler？ 在项目目录运行 npm install @cloudflare/kv-asset-handler，或使用 pnpm add / yarn add / bun add。 ### @cloudflare/kv-asset-handler 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @cloudflare/kv-asset-handler 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @cloudflare/kv-asset-handler 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @cloudflare/kv-asset-handler 可以商用吗？ @cloudflare/kv-asset-handler 使用 MIT OR Apache-2\.0 许可。可在 MIT、Apache-2\.0 中任选其一遵守。选择 MIT 时，宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @cloudflare/kv-asset-handler 的下载量有多少？ 根据 npm 官方下载统计，@cloudflare/kv-asset-handler 在 2026/10/10 – 2026/11/08 这 30 天内被下载 124,564,202 次，日均约 4,152,140 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @cloudflare/kv-asset-handler 还在维护吗？ 最新版本 0\.5\.0 发布于 2026/05/01（6 个月前）；至今共发布 26 个版本，其中过去 12 个月发布了 3 个；首次发布于 2019/09/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。