@cloudflare/kv-asset-handler 页面存档备份,存于互联网档案馆
kv-asset-handler 一个开源库,用于管理从 工人 KV 内置 云花岗工人 函数. kv-asset-handler 设计用于: 工人工地,包含在 响尾蛇我们部署工人项目的指挥线工具.
kv-asset-handler 运行为 Cloudflare 函数的一部分,因此您可以自定义 怎么样 财务报告和审定财务报表 何时 您的静态资产被装入, 以及定制 这些资产如何行为 在他们发送到客户之前.
大多数用户和网站不需要这些定制,只想为其静态构建的应用程序服务. 简单的用例,你可以检查出来 云旗页我们的电池包括了在Cloudflare的边缘网络上部署静态站点的方法。 工人站点被设计为Cloudflare Pages的前身,所以检查Pages,如果你只是想部署你的静态站点而不需要任何特殊的定制!
用户 对 想要定制他们的资产, 想要在他们的静态资产之上积累复杂的经验, kv-asset-handler (和默认) 工人工地模板,它规定与 Wrangler + Workers Sites 一起使用)允许您自定义缓存行为,头条,以及其它任何关于您的工人如何为存储在Workers KV的站点装入静态资产.
Cloudflare工人Discord服务器是工人用户获得帮助,分享反馈,合作改善我们的平台的活跃地. 这个 #workers 特别频道是聊天的好地方 kv-asset-handler,并为用户使用这些工具建立酷酷的经验! 如果你有问题,想分享你的工作, 或者提供反馈, 和我们一起Discord打个招呼来啊!
安装
将此软件包添加到您的 package.json 在您的根中运行此选项
项目目录 :
npm i @cloudflare/kv-asset-handler
使用量
这个软件包的设计是为了与 工人场地。 。 。 .
getAssetFromKV
获取 Asset from KV( Evt) QQ 答应
getAssetFromKV 是需要一个 Evt 对象( 包含 a Request (单位:千美元) waitUntil返回 a Response 如果请求与 KV 中的资产相匹配, 则对象将丢出 KVError。 。 。 .
示例
此示例检查 KV 中存在一个值, 如果存在则返回, 如果存在, 则返回 404 。 它也服务于Index.html from /。 。 。 .
返回时
getAssetFromKV 返回 a Promise<Response> 与 Response 是请求的资产主体.
已知要抛出的错误有:
- 方法不完全错误
- 非 Found 错误
- 内部错误
ES 模块
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);
},
};
服务工作者
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。这适用于大多数静态站点生成器,但您可以通过将自己的功能传递为 mapRequestToAsset。该职能应当包括: Request 对象作为其唯一的参数,并返回新参数 Request 对象,在资产表/ KV 中查找更新路径.
用于 SPA 绘图 serveSinglePageApp 函数
示例
脱 /docs 在Cloudflare的KV中查找资产之前.
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 缓存配置选项,也可以为您工作人的回复同时发送浏览器缓存头。 默认值如下:
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 命名空间具有约束力 名称 __STATIC_CONTENT。 。 。 .
进一步假设,这个命名空间由静态资产组成,如HTML,CSS,JavaScript,或图像文件,从一个相对路径中键入,该路径大致匹配了所请求的所假设的URL路径名.
在ES模块格式中,需要这个参数,并且可以从 env。 。 。 .
ES 模块
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 模块
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 页眉。如果资源在缓存中,在返回之前,ETag总是被削弱.
默认值为 'strong'。 。 。 .
辅助功能
mapRequestToAsset
地图请求 请求
Cloudflare KV 中用于映射密钥来源请求的默认函数 .
选择任何结束于 / 或评价到 HTML 文件及附件 index.html 或者说 /index.html 在您的 KV 命名空间中查找 .
serveSinglePageApp
服务 SinglePageApp( 请求) 请求
用于将请求映射到单一根的自定义处理器 : index.html. 最常见的使用案例是单页应用程序 - 有应用中路由的框架 - 如React Router,VueJS等. 这需要零辩论.
import { getAssetFromKV, serveSinglePageApp } from '@cloudflare/kv-asset-handler'
...
let asset = await getAssetFromKV(event, { mapRequestToAsset: serveSinglePageApp })
缓存重新验证和标签
所有答复都来自缓存(包括来自 cf-cache-status: MISS包括: etag 用于识别资源版本的响应头。 这个 etag 值与 ASSET_MANIFEST。每次资产变化时都会更新它,这样看起来: etag: <filename>.<hash of file contents>.<extension> (预算外). etag: index.54321.html) (中文(简体) ).
资源用于 etag 允许浏览器使用 if-none-match 请求未来对该资源提出有条件的请求。 这有两个主要好处:
- 当一个请求
if-none-match值与etagcloudflare 缓存中的资源304 Not Modified没有身体的响应,节省带宽. - 对服务器上文件的更改立即在浏览器中反映 - 即使缓存控制指令
max-age未过期.
禁用 etag
转身 etags 关,您必须绕过缓存 :
/* Turn etags off */
let cacheControl = {
bypassCache: true,
};
语法和比较上下文
kv-asset-handler 设置并评价 强验证符保留 etag 完整性,数值的格式偏离 RFC2616 建议: etag 有引号这是故意的。 Cloudflare 缓存应用 W/ 全部前缀 etags 引用字符串 -- -- 一个转换 etag 给客户端的"弱验证器".