★ FEATURED ARTICLE 文档教程后端【免费下载链接】koa2-note《Koa2进阶学习笔记》已完结项目地址https://gitcode.com/gh_mirrors/ko/koa2-note点击查看免费下载本文基于《Koa2进阶学习笔记》开源仓库中的 note/static/middleware.md 编写是 Koa2 静态资源加载篇章的中间件方案详解。读完本文你将掌握如何在 Koa2 应用中通过koa-static中间件一键托管 CSS、JS、图片、HTML 等静态文件并了解其目录组织、运行方式、常用配置项以及与仓库中原生 Koa2 静态资源服务器实现方案的对比取舍。背景从手写静态服务器到中间件一键托管在 Koa2 中默认情况下应用不会自动处理静态资源请求。仓库中同时收录了两套解决方案原生手写方案note/static/server.md 及其配套 demo demo/static-server/自己实现 MIME 类型解析、目录遍历、文件读取与 404 处理中间件方案本文主题note/static/middleware.md 及其配套 demo demo/static-use-middleware/引入koa-static中间件一行app.use(...)即可完成静态资源托管。koa-static的典型使用场景是前后端不分离或同源部署时由 Koa2 服务直接对外提供 HTML 页面、样式表、脚本与图片它也是本项目第 12 章项目框架搭建中 Web 服务对外提供页面资源的基础能力之一。一、安装依赖demo 的依赖版本与运行环境仓库中 demo/static-use-middleware/package.json 明确给出了该 demo 的依赖与运行环境约束{ name: static-use-middleware, version: 1.0.0, main: index.js, scripts: { start: node index.js }, dependencies: { koa: ^2.3.0, koa-static: ^3.0.0 }, engines: { node: 7.6.0, npm: 3.0.0 } }关键信息核心依赖仅两个koa^2.3.0与koa-static^3.0.0engines.node要求7.6.0这是因为 Koa2 的中间件基于async/await编写需要 Node.js 7.6 及以上版本的原生支持提供了npm start快捷启动脚本等价于执行node index.js。安装依赖npm install二、最小可运行示例完整代码与逐行解析仓库 demo/static-use-middleware/index.js 中的核心代码如下与笔记文档中的示例保持一致const Koa require(koa) const path require(path) const static require(koa-static) const app new Koa() // 静态资源目录对于相对入口文件index.js的路径 const staticPath ./static app.use(static( path.join( __dirname, staticPath) )) app.use( async ( ctx ) { ctx.body hello world }) app.listen(3000, () { console.log([demo] static-use-middleware is starting at port 3000) })逐行拆解这段代码引入模块koa创建应用实例path用于路径拼接static即koa-static中间件工厂函数定义静态目录staticPath ./static是相对于入口文件index.js的相对路径实际目录位于 demo/static-use-middleware/static/注册中间件app.use(static(path.join(__dirname, staticPath)))将__dirname入口文件所在目录的绝对路径与相对路径拼接得到静态目录的绝对路径后传给koa-static。这里使用path.join而非字符串拼接是为了保证跨平台Windows/Linux/macOS的路径分隔符正确性后置业务中间件当请求未被静态中间件命中例如访问不存在的资源路径时请求会继续向下流转到该中间件返回hello world监听端口app.listen(3000)启动服务并打印启动日志。需要说明的是仓库中实际的 index.js 将第 4 步的后置中间件以注释形式保留app.use( async ( ctx ) { ctx.body hello world })其用意是提示读者静态中间件命中请求后即完成响应后续中间件用于兜底处理其他请求。从中间件的洋葱模型看可参考 note/start/middleware.md 对中间件开发与使用的讲解koa-static在内部对命中静态资源的请求直接设置ctx.body结束响应对未命中的请求调用next()放行。三、静态资源目录的组织方式演示用静态资源目录 demo/static-use-middleware/static/ 的结构如下static/ ├── css/ │ └── style.css # 页面样式 ├── image/ │ └── nodejs.jpg # 页面图片 ├── js/ │ └── index.js # 页面脚本 └── index.html # 入口页面作为入口的 static/index.html 以根路径相对引用的方式加载上述资源!DOCTYPE html html head meta charsetUTF-8 titleindex/title link relstylesheet href/css/style.css / /head body h1 classh1koa2 simple static server/h1 img src/image/nodejs.jpg / script src/js/index.js/script /body /html注意href/css/style.css、src/image/nodejs.jpg、src/js/index.js中的/均以 Web 根路径为起点与koa-static托管的目录一一对应。也就是说浏览器请求/css/style.css时中间件会将其映射到静态目录下的css/style.css文件。四、运行与效果验证启动服务两种方式等价# 方式一直接运行 node index.js # 方式二使用 package.json 中配置的脚本 npm start启动成功后终端输出[demo] static-use-middleware is starting at port 3000随后可验证三类典型访问路径效果截图与笔记文档一致访问http://localhost:3000根路径koa-static默认以index.html作为目录默认首页返回页面访问http://localhost:3000/index.html显式请求 HTML 页面浏览器正常渲染出标题koa2 simple static server、图片与脚本效果访问http://localhost:3000/js/index.js静态 JS 文件被正确输出其内容为(function( ){ alert(hello koa2 static server) console.log(hello koa2 static server) })()浏览器控制台会打印hello koa2 static server五、koa-static 常用配置项koa-static是基于koa-send封装的高层中间件其工厂函数签名形如static(root, opts)。结合koa-static^3.0.0的公开接口以下常用配置项供实战参考具体行为以实际安装版本为准配置项默认值作用说明root必填静态资源目录的绝对路径即上文path.join(__dirname, staticPath)的结果maxage0浏览器缓存max-age单位为毫秒如设置为3600000则静态资源可被浏览器缓存 1 小时indexindex.html访问目录时默认返回的首页文件名设为false可禁用目录默认首页hiddenfalse是否允许传输以.开头的隐藏文件默认不允许deferfalse是否延迟执行静态中间件为true时先执行其他中间件再尝试静态资源匹配适合需要先做鉴权等前置处理的场景gziptrue当目录下存在同名.gz文件时优先返回 gzip 压缩版本brtrue当目录下存在同名.br文件时优先返回 brotli 压缩版本setHeaders无自定义响应头函数形如(res, path, stat) {}可在其中追加Cache-Control等响应头在笔记的基础用法中所有可选项均使用默认值只传入静态目录绝对路径即可满足常规托管需求当需要控制缓存策略如为图片、JS 设置长缓存或调整默认首页时再按上表传入第二参数。六、与原生手写方案对比为什么用中间件仓库在 demo/static-server/ 中提供了不借助任何中间件的原生 Koa2 静态服务器实现对应 note/static/server.md其入口 index.js 需要自行完成以下工作MIME 类型解析通过util/mimes.js维护 css、html、jpg、js 等十余种扩展名到 MIME 类型的映射表再用path.extname()解析请求 URL 的扩展名并查表路径存在性判断与 404 处理通过util/content.js使用fs.existsSync()判断请求路径是否存在不存在则返回404 Not Found! o(╯□╰)o目录与文件分流用fs.statSync()判断是目录还是文件目录走util/dir.jsutil/walk.js遍历生成 HTML 目录列表文件走util/file.js以二进制模式读取二进制与文本分流输出图片等二进制资源通过ctx.res.writeHead(200)ctx.res.write(_content, binary)输出文本资源则直接赋值ctx.body。对比可见koa-static将这些底层细节全部封装进了中间件内部使用方只需要指定一个绝对路径目录。从工程实践角度两者各有适用场景学习底层原理阅读 note/static/server.md 与 demo/static-server/util/ 下的content.js、dir.js、file.js、walk.js、mimes.js实现能深入理解 HTTP 静态服务的完整流程业务快速落地使用koa-static代码量从近百行的工具函数收敛为app.use(static(path.join(__dirname, staticPath)))一行且天然获得 MIME 推断、目录默认首页、缓存控制等能力这正是笔记将本方案作为静态资源加载章节推荐的中间件用法。结语通过 demo/static-use-middleware/ 这一最小示例可以看到在 Koa2 中托管静态资源的核心就三步安装koa-static、定义静态目录绝对路径、app.use()注册中间件。本文沿笔记脉络补充了依赖版本、目录组织、配置项与原生实现对比读者可结合仓库中的两套 demo 源码中间件版 与 原生版对照学习从会用进阶到懂原理。赞分享文档教程后端【免费下载链接】koa2-note《Koa2进阶学习笔记》已完结项目地址https://gitcode.com/gh_mirrors/ko/koa2-note点击查看免费下载相关推荐koa2-note 实战用 koa-bodyparser 中间件解析 Koa2 POST 请求体koa2 note 实战用 koa bodyparser 中间件解析 Koa2 POST 请求体 在 Koa2 中GET 请求参数可以通过 ctx.quer文档教程后端koa2-note 实战koa-router 路由中间件——子路由拆分、routes() 与 allowedMethods() 完整解析koa2 note 实战koa router 路由中间件——子路由拆分、routes 与 allowedMethods 完整解析 本文基于《Koa2进阶学习笔文档教程后端Koa2 原生路由实战不依赖 koa-router 实现 URL 路由匹配koa2-note 学习笔记 2.1Koa2 原生路由实战不依赖 koa router 实现 URL 路由匹配koa2 note 学习笔记 2.1 本篇基于 koa2 note 仓库的 no文档教程后端上一篇告别命令行与驱动用 Tango 在浏览器里免费搞定安卓在线调试下一篇Armlogic S9XXX Armbian 系统版本升级指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
