koa2-note 实战：使用 koa-static 中间件为 Koa2 应用托管静态资源

• 文档
• 教程
• 后端

本文基于《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.0）；
• engines.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') })

逐行拆解这段代码：

1. 引入模块：koa创建应用实例，path用于路径拼接，static即koa-static中间件工厂函数；
2. 定义静态目录：staticPath = './static'是相对于入口文件index.js的相对路径，实际目录位于 demo/static-use-middleware/static/；
3. 注册中间件：app.use(static(path.join(__dirname, staticPath)))将__dirname（入口文件所在目录的绝对路径）与相对路径拼接，得到静态目录的绝对路径后传给koa-static。这里使用path.join而非字符串拼接，是为了保证跨平台（Windows/Linux/macOS）的路径分隔符正确性；
4. 后置业务中间件：当请求未被静态中间件命中（例如访问不存在的资源路径）时，请求会继续向下流转到该中间件，返回hello world；
5. 监听端口：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 charset="UTF-8"> <title>index</title> <link rel="stylesheet" href="/css/style.css" /> </head> <body> <h1 class="h1">koa2 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

随后可验证三类典型访问路径（效果截图与笔记文档一致）：

1. 访问http://localhost:3000（根路径）：koa-static默认以index.html作为目录默认首页返回页面：

2. 访问http://localhost:3000/index.html：显式请求 HTML 页面，浏览器正常渲染出标题koa2 simple static server、图片与脚本效果：

3. 访问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的公开接口，以下常用配置项供实战参考（具体行为以实际安装版本为准）：

在笔记的基础用法中，所有可选项均使用默认值，只传入静态目录绝对路径即可满足常规托管需求；当需要控制缓存策略（如为图片、JS 设置长缓存）或调整默认首页时，再按上表传入第二参数。

六、与原生手写方案对比：为什么用中间件

仓库在 demo/static-server/ 中提供了不借助任何中间件的原生 Koa2 静态服务器实现（对应 note/static/server.md），其入口 index.js 需要自行完成以下工作：

1. MIME 类型解析：通过util/mimes.js维护 css、html、jpg、js 等十余种扩展名到 MIME 类型的映射表，再用path.extname()解析请求 URL 的扩展名并查表；
2. 路径存在性判断与 404 处理：通过util/content.js使用fs.existsSync()判断请求路径是否存在，不存在则返回404 Not Found! o(╯□╰)o！；
3. 目录与文件分流：用fs.statSync()判断是目录还是文件，目录走util/dir.js+util/walk.js遍历生成 HTML 目录列表，文件走util/file.js以二进制模式读取；
4. 二进制与文本分流输出：图片等二进制资源通过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 源码（中间件版 与 原生版）对照学习，从"会用"进阶到"懂原理"。

• 文档
• 教程
• 后端