eggjs/koa-static-cache 版本演进与静态缓存中间件实战解析【免费下载链接】egg Born to build better enterprise frameworks and apps with Node.js Koa. https://307.run/eggcode项目地址: https://gitcode.com/gh_mirrors/eg/egg导读eggjs/koa-static-cache是 Egg 框架体系内置的 Koa 静态文件缓存中间件它以初始化即缓存、可选内存驻留、MD5 ETag、原生 gzip 支持等特性区别于同类静态服务中间件。本文以该包的 CHANGELOG.md 为主线梳理其从 1.0 到 7.0 的功能演进脉络并结合 核心源码 与 测试用例 深入讲解每个配置项的实现原理、实战用法以及在 Egg 应用中的落地方式。读完本文你将掌握如何独立使用该中间件为任意 Koa 应用提供高性能静态资源服务并理解其缓存、压缩、条件请求的完整工作链路。一、定位与血缘从 koajs/static-cache 到 eggjs/koa-static-cache从 CHANGELOG.md 的早期条目可以看到该包的历史可以追溯到 2013 年 12 月的1.0.0彼时它还是 Koa 1 时代的koajs/static-cache。在 6.0.0 版本中项目完成了两个关键动作迁移为 TypeScript、包名变更为eggjs/koa-static-cache正如 README.md 所注明的Forked from koajs/static-cache, refactor with TypeScript to support CommonJS and ESM both。根据 README.md它与koajs/static这类普通静态中间件的本质区别在于不支持目录浏览和index.html自动索引默认以流式方式输出可选将文件内容常驻内存options.buffer在初始化阶段就缓存全部资产文件更新需要重启进程可用options.preload false关闭使用文件内容的 MD5 作为 ETag支持磁盘上的预压缩.gz文件类似 nginx 的gzip_static模块对应 6.1.0 中引入的usePrecompiledGzip。该中间件在 plugins/static 中被描述为 Static server plugin for egg, base on eggjs/koa-static-cache是整个 Egg 静态资源服务能力的地基。二、版本演进时间线CHANGELOG 背后的功能成长史CHANGELOG.md 完整记录了十余年的演进下面按阶段还原每一类核心能力是如何一步步沉淀出来的。1.x静态缓存的基础能力成形2013–20141.0.02013-12-21基于yield* next的 Koa 1 风格中间件诞生1.0.72014-03-26新增options.gzip控制 gzip 压缩支持 Buffer 与流两种形态的 gzip 输出1.0.82014-03-31新增options.dir默认值为process.cwd()增加Vary响应头按文件长度判断是否需要 gzip并通过compressible判定类型可压缩性1.0.92014-03-31新增 url 前缀options.prefix1.1.02014-07-16以mime-types替换mime移除 onerror/destroy 处理交由 Koa 负责1.2.02014-09-18以this.path作为 key 时先进行decodeURI解码。2.x协议与方法的收敛2014–20172.0.02014-11-14升级 Koa且仅响应 GET 与 HEAD 请求其它方法直接放行给下游中间件2.0.12014-12-02容忍异常路径例如//index.html这类双斜杠路径2.0.22015-01-05修复 Windows 平台下路径 normalize 的 bug。3.x动态加载与内存缓冲20153.0.02015-01-06新增options.buffer false以完全不缓存文件内容仅流式输出支持文件动态加载对应dynamic雏形3.0.12015-01-06正式引入dynamic选项支持动态加载并使用stat判断请求目标是否为文件夹3.0.32015-03-28修复动态模式下缓存未生效的问题3.1.02015-03-28合并 gzip 相关 PR#333.1.1/3.0.2连续修复 Windows 平台options.prefix的路径 bug3.1.22015-07-08修复动态文件场景下的报错3.1.32015-11-26修复 mtime 比较逻辑3.1.52016-03-02修复 Windows 平台动态加载文件的 bug3.1.62016-03-22不吞掉下游中间件的错误3.2.02017-01-07新增options.preload控制初始化阶段是否预加载缓存3.1.72016-04-07升级mz至 2.4.0。4.x–5.xKoa 2 时代与工程化打磨2017–20204.0.02017-02-21重构为先检查prefix再计算避免无谓的路径运算5.0.02017-04-01正式支持 Koa 25.0.12017-04-19支持 Node.js v7.6.05.1.02017-06-01files存储支持 LRU 淘汰5.1.12017-06-13只加载options.dir目录下的文件安全边界5.1.22018-02-06依赖版本放宽为^5.1.32020-04-29修复preload false时 alias 失效的问题5.1.42020-08-03清理无用 require、修正时间比较逻辑、修复 mtime#93。6.xTypeScript 化与现代工程改造20256.0.02025-01-12drop Node.js 18.19.0 support通过tshy同时支持 CJS 与 ESM迁移为eggjs/koa-static-cache升级 engines 至 18.19.0全面引入 TypeScript、ESLint、GitHub Actions 等工作流6.1.02025-03-12使用eggjs/compressible进行可压缩性判定。7.0.0面向 Egg 4 的收口当前版本见 package.json 为7.0.2-beta.25声明了明确的破坏性变更drop Node.js 22.18.0 supportonly support egg4。注意CHANGELOG 顶部声明后续版本的发布说明将改用 GitHub Releases 页面配合release.yml工作流生成CHANGELOG 文件本身不再逐条维护。三、核心源码解析一次静态缓存请求的完整链路3.1 Options 全量配置说明对照 src/index.ts 的Options接口中间件支持的全部配置项如下配置项类型默认值说明dirstringprocess.cwd()静态资源根目录maxAgenumber0Cache-Control 的 max-age 秒数cacheControlstring | functionundefined自定义 Cache-Control 头优先级高于maxAge传函数时以文件名为参数调用bufferbooleanfalse是否将文件内容缓存在内存中而非每次流式读取gzipbooleanfalse当请求Accept-Encoding含 gzip 时运行时压缩响应usePrecompiledGzipbooleanfalse优先使用磁盘上的.gz预压缩文件类似 nginxgzip_staticaliasobject{}URL 别名映射prefixstringURL 前缀filterfunction | string[]undefined初始化扫描时的文件过滤器数组形式表示白名单dynamicbooleanfalse是否支持请求时动态加载未缓存的新文件preloadbooleantrue是否在初始化时预加载全部文件通常与dynamic配合使用filesobject | FileStoreundefined外部文件缓存对象支持传入普通对象或带get/set的 LRU 存储函数签名支持四种重载staticCache()、staticCache(dir)、staticCache(options)、staticCache(dir, options, files)其中dir参数的优先级高于options.dir这一点在 测试用例 中有专门验证。3.2 请求处理主链路在 src/index.ts 中中间件的主流程清晰可循方法过滤仅接受HEAD与GET其它方法直接await next()放行前缀检查ctx.path.startsWith(options.prefix)不满足则放行这是 4.0.0 check prefix first to avoid calculate 的优化落地路径归一化先decodeURIComponent解码中文等 URL 编码路径再path.normalize处理//index这类异常路径别名解析命中options.alias则替换 filename缓存命中命中files.get(filename)直接使用未命中且dynamic开启时执行安全校验后loadFile动态加载安全边界动态加载前通过fullpath.startsWith(dir)与stats.isFile()双重校验确保只能访问options.dir之下的文件这是 5.1.1 与 目录穿越测试 所保障的条件请求非 buffer 模式下每次请求会fs.stat检查 mtime若文件变更则清除旧的 md5/length随后设置Last-Modified与 MD5ETag若ctx.fresh为真则直接返回304响应头设置Content-Type、Content-Length、Cache-Control默认public, max-ageN、Content-MD5gzip 决策enableGzip file.length 1024 acceptGzip compressible(file.type)满足时才压缩压缩源优先取usePrecompiledGzip读到的磁盘.gz文件否则用zlib.gzip实时压缩输出buffer 模式直接输出内存 Buffer否则createReadStream流式输出。3.3 loadFile 与初始化预加载loadFile 在初始化预加载options.preload ! false或动态加载时被调用其职责包括以path.join(options.prefix, name)作为缓存 key因此 URL 与缓存 key 天然一致用mime-types推断 MIME 类型兜底为application/octet-stream记录mtime、length并计算文件内容的MD5base64作为 ETag 与 Content-MD5options.cacheControl为函数时以文件名调用并缓存结果options.buffer为真时把文件内容整体读入内存。初始化扫描使用fs-readdir-recursive默认跳过点开头的隐藏文件与node_modules目录这正是测试中/.gitignore返回 404 的原因。四、实战在 Koa 应用中独立使用4.1 安装与最小示例npm install eggjs/koa-static-cacheconst path require(path); const { staticCache } require(eggjs/koa-static-cache); app.use( staticCache(path.join(__dirname, public), { maxAge: 365 * 24 * 60 * 60, }), );4.2 别名Alias免重定向的资源映射当请求/favicon.png时需要返回/favicon-32.png无需重定向、无需存储重复文件const options { alias: { /favicon.png: /favicon-32.png, }, };别名处理在中间件主链路中位于路径归一化之后、缓存查询之前因此别名 key 必须与归一化后的 URL 形态一致。4.3 共享 files 对象多目录合并与动态调整合并多个目录进一个中间件减少函数栈层级与哈希查找次数const files {}; app.use(staticCache(/public/js, {}, files)); staticCache(/public/css, {}, files); // 追加更多文件到同一 files 对象运行时修改单个文件的缓存策略例如单独调低/package.json的 maxAgeconst files {}; app.use(staticCache(/public, { maxAge: 60 * 60 * 24 * 365 }, files)); files[/package.json].maxAge 60 * 60 * 24 * 30;这一能力在 测试用例 中得到验证修改后请求/package.json会返回Cache-Control: public, max-age1。4.4 动态模式 LRU避免内存无限增长dynamic: true时每次新文件请求都会写入缓存若不设上限在大量不同文件场景下可能 OOM。README 推荐传入实现了get(key)/set(key, value)的 LRU 实例const LRU require(lru-cache); const files new LRU({ max: 1000 }); app.use( staticCache({ dir: /public, dynamic: true, files, }), );源码 中的FileManager会通过typeof store.set function typeof store.get function自动识别传入的是 LRU 存储还是普通对象动态 LRU 测试 验证了容量为 1 的 LRU 中旧条目会被正确淘汰。4.5 filter 的两种形态// 函数形态自定义过滤逻辑如跳过源码文件 staticCache({ dir: /public, filter: (file) !file.endsWith(.map) }); // 数组形态仅白名单指定文件 staticCache({ dir: /public, filter: [index.html, app.js] });数组形态在 src/index.ts 中被实现为options.filter.includes(file)的判定filter 测试 验证了白名单之外的文件如README.md会返回 404。五、在 Egg 框架中的落地eggjs/static 插件eggjs/koa-static-cache是 Egg 内置静态服务插件eggjs/static的底层实现见 plugins/static/package.json 中的eggjs/koa-static-cache: workspace:*依赖以及 中间件源码 中直接调用staticCache(newOptions)。5.1 Egg 侧的默认配置根据 config.default.tsEgg 中默认值如下prefix:/public/dir:path.join(appInfo.baseDir, app/public)dynamic:true支持懒加载preload:falsemaxAge: 生产环境31536000一年其它环境0见 config.prod.tsbuffer: 生产环境true其它环境falsemaxFiles:1000仅dynamic开启时生效作为 LRU 容量插件侧还通过koa-range中间件为静态资源补充 Range 请求支持并用koa-compose将多个目录的 staticCache 组合为单一中间件。dir支持[dir1, dir2, ...]或[{ prefix: /static2, dir: dir2 }]多目录数组形态且目录不存在时会自动mkdirSync创建。5.2 行为差异重要非生产环境资源不被缓存buffer: false、maxAge: 0、preload: falsedynamic: true改动即时生效便于开发调试生产环境buffer: true且maxAge: 31536000文件在首次访问后被缓存更新静态资源需要重启进程。这也是 CHANGELOG 中preload、dynamic、buffer等选项演进十多年后最终在 Egg 生态中的标准姿势。六、关键行为速查来自测试用例的证据test/index.test.ts 中沉淀了一批值得在生产中注意的行为约定行为测试依据目录穿越被拦截/%2E%2E/package.json返回 404L510-L520隐藏文件.gitignore不提供服务L191-L193带 query string 的请求正常处理/src/index.ts?querystringL221-L223携带If-None-Match的 HEAD/GET 返回 304L195-L211非 GET/HEAD 方法放行给下游L217-L219未开启dynamic时新增文件返回 404L324-L333动态模式下新增文件返回 200L335-L355动态模式下隐藏文件.a.js仍返回 404L402-L411请求路径是文件夹时返回 404L427-L432gzip 请求返回Content-Encoding: gzip且带Vary: Accept-Encoding不支持的客户端收到原文L279-L311ETag 与 Content-MD5 等于文件内容 MD5L239-L244七、升级注意事项与适用前提结合 CHANGELOG 的破坏性变更声明从旧版本升级到 7.x 需要关注Node 版本6.x 要求 Node.js ≥ 18.19.07.x 进一步提升为Node.js ≥ 22.18.0package.json 的engines字段同步声明Egg 版本7.x 仅支持egg4升级前需确认框架版本包名变更6.0.0 起包名从koa-static-cache变为eggjs/koa-static-cache旧引入路径需同步更新模块格式6.0.0 起同时支持 CJS 与 ESMtshy双格式输出main/module/types均已指向dist产物。结语从 2013 年的 Koa 1 中间件到如今支撑 Egg 4 的 TypeScript 现代实现eggjs/koa-static-cache的 CHANGELOG 本身就是一份完整的静态缓存工程实践档案。理解preload/dynamic的加载策略取舍、buffer的内存与实时性权衡、gzip 的三级压缩来源以及 files/LRU 的缓存管理方式将帮助你在独立 Koa 应用与 Egg 框架两个层面都能把静态资源服务调教到最优。【免费下载链接】egg Born to build better enterprise frameworks and apps with Node.js Koa. https://307.run/eggcode项目地址: https://gitcode.com/gh_mirrors/eg/egg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
