Node.js使用Koa搭建基础项目
本文介绍如何使用Node.js和Koa框架搭建基础Web项目。内容涵盖项目初始化、ES6+异步语法的应用、原生路由与koa-router中间件的配置、静态资源托管以及模板引擎的使用，帮助开发者快速掌握Koa的核心开发流程。
Koa 是一个由 Express 原班人马开发的轻量级服务端框架。
相较于 Express，Koa 不仅提供了更高的自由度，允许开发者自行引入中间件，更关键的是它采用了 ES6 和 async/await 语法，从而有效避免了回调地狱的问题。
由于代码层面的升级，Koa2 要求 Node.js 环境版本至少在 v7.60 以上。
一、创建项目
首先手动创建一个项目目录，并快速生成一个 package.json 文件。
npm init -y
安装 koa（当前版本为 2.4.1）。
npm install koa -S
接着创建一个 app.js 文件。
// app.js
const Koa = require('koa');
const app = new Koa();
app.use(async ctx => {
ctx.body = 'Wise Wrong';
});
app.listen(3000);
最后，在 package.json 中添加启动指令。
至此，一个最基础的 Koa 应用便搭建完成。
执行 npm start 命令，并在浏览器中访问 http://localhost:3000/ 即可查看运行效果。
如果觉得手动创建项目过于繁琐，可以使用脚手架工具 koa-generator 来自动生成项目结构。
npm install koa-generator -g
koa2 project_name
在项目目录下执行 npm install 安装依赖，随后通过 npm start 启动项目。
对于初次接触 Koa 的开发者，建议先阅读相关博客文章，再使用脚手架工具，这样能更好地理解各个依赖包的作用。
二、配置路由
在上面的 app.js 中，ctx 是一个 Koa 提供的 Context 对象，它封装了 request 和 response。
每一次 HTTP 请求都会创建一个新的 Context 对象。
我们可以通过 Context.request.path 获取用户请求的路径，并通过 Context.response.body 向用户发送内容。
Koa 默认返回的类型是 text/plain，若要返回 HTML 文件或模块文件，则需要修改 Context.response.type。
此外，Context.response 可以简写，例如 Context.response.type 可简写为 Context.type，Context.response.body 可简写为 Context.body。
在项目目录下创建一个存放 HTML 文件的 views 目录，并在该目录下创建 index.html，然后修改 app.js。
// app.js// 原生路由
const Koa = require('koa');
const fs = require('fs');
const app = new Koa();
app.use(async (ctx, next) => {
if (ctx.request.path === '/index') {
ctx.type = 'text/html';
ctx.body = fs.createReadStream('./views/index.html');
} else {
await next();
}
});
app.listen(3000);
随后在浏览器中访问 http://localhost:3000/index 即可看到 index.html 页面，访问其他地址则显示 not found。
这种处理 URL 的方式显得较为笨拙，因此我们需要引入路由中间件 koa-router。
npm install koa-router -S
需要注意的是，在导入 koa-router 时，需要在末尾加一个括号。
const router = require('koa-router')();
这相当于：
const koaRouter = require('koa-router');
const router = koaRouter();
创建一个 routes 目录，用于存放路由文件，并在目录下创建 index.js。
// routes/index.js
const fs = require('fs');
const router = require('koa-router')()
router.get('/index', async (ctx, next) => {
ctx.type = 'text/html';
ctx.body = fs.createReadStream('./views/index.html');
});
module.exports = router
这里还可以使用 prefix 方法，为文件中的所有接口添加一个 baseUrl。
// router.prefix('/about')
修改 app.js。
// app.js
const Koa = require('koa');
const app = new Koa();
const index = require('./routes/index')
app.use(index.routes(), index.allowedMethods())
app.listen(3000);
上面的 allowedMethods 用于校验请求的方法，如果使用 POST 请求访问 GET 接口，将直接返回失败。
另外，还可以在 URL 中添加变量，然后通过 Context.params.name 进行访问。
router.get('/about/:name', async (ctx, next) => {
ctx.body = `I am ${ctx.params.name}!`;
});
三、静态资源
在上面的 index.html 中，如果需要引入 CSS 等静态资源，就需要用到 koa-static。
npm install koa-static -S
创建一个目录 public 用来存放静态资源。
然后在 app.js 中添加以下代码。
const static = require('koa-static');
// 将 public 目录设置为静态资源目录
const main = static(__dirname + '/public');
app.use(main);
事实上，这三行代码还可以进一步优化。
app.use(require('koa-static')(__dirname + '/public'));
随后就能在 index.html 中引入对应的文件了。
四、模板引擎
上面的路由是使用 fs 模块直接读取 HTML 文件。
开发时更推荐使用 koa-views 中间件来渲染页面。
npm install koa-views -S
在 app.js 中将 views 目录设定为模板目录。
const views = require('koa-views')
app.use(views(__dirname + '/views'));
然后在路由文件中，就能使用 render 方法了。
// routes/index.js
const router = require('koa-router')()
router.get('/index', async (ctx, next) => {
await ctx.render('index');
});
module.exports = router
以上是直接渲染 HTML 文件的方法，如果要引入模板引擎，可以添加 extension 字段来设定模板类型。
app.use(views(__dirname + '/views', {
extension: 'pug' // 以 pug 模版为例
}))
五、结语
如果将 Express 比作 WebStorm，那么 Koa 就是 Sublime。
当 Express 流行时，其冗杂的依赖项备受开发者诟病。
因此，Express 团队将 Express 拆卸得只剩下最基本的骨架，让开发者自行组装，这就是 Koa。
正如文中所述，从零开始太过繁琐，可以使用脚手架 koa-generator 来快速开发。
不过我更推荐，在熟悉 Koa 之后，搭建一个适合自己项目的脚手架。
不然为何不直接用 Express 呢？
我想这也是 Koa 的官方文档中没有提到 generator 工具的原因吧。
怎么在本地运行JavaScript脚本：Node.js下载安装与环境配置教程
2026-11-05 09:02:33
JavaScript开发环境怎么搭建：Node.js安装与VS Code配置指南
2026-11-03 23:36:59
JavaScript零基础入门：环境搭建与第一个Hello World
2026-11-03 23:34:09
NW.js 是什么：基于 Chromium 和 Node.js 的桌面应用框架
2026-11-03 15:14:00
nvm、n 和官方安装包：哪种 Node.js 升级方式更适合你
2026-11-03 14:54:28