Koa系列教程：1. 创建项目

结论

mkdir koa-demo && cd koa-demo
npm init -y
npm install koa

// 1. 引入Koa模块（CommonJS规范，Node.js默认支持）
const Koa = require('koa');// 2. 创建Koa应用实例
const app = new Koa();// 3. 定义端口（推荐3000，避免与系统端口冲突）
const port = 3000;// 4. 中间件1：演示洋葱模型的“请求进入”阶段
app.use(async (ctx, next) => {console.log('中间件1：请求开始 - 记录时间');const start = Date.now();  // 记录请求开始时间// 调用next()，进入下一个中间件（核心：洋葱模型的“进入”环节）await next();// 下一个中间件执行完成后，回到这里（洋葱模型的“返回”环节）const end = Date.now();console.log(`中间件1：请求结束 - 耗时${end - start}ms`);
});// 5. 中间件2：核心业务逻辑（处理请求并返回响应）
app.use(async (ctx) => {console.log('中间件2：处理请求');// ctx是Koa的核心上下文对象，包含请求（ctx.request）和响应（ctx.response）信息ctx.status = 200;  // 设置响应状态码（200表示成功）ctx.type = 'text/html';  // 设置响应内容类型ctx.body = ``;  // 设置响应内容（即返回给浏览器的内容）
});// 6. 启动Koa服务，监听指定端口
app.listen(port, () => {console.log(`Koa服务已启动，访问地址：http://localhost:${port}`);
});

node app.js

扩展全文

Koa作为Express原班人马打造的Node.js Web框架，以“轻量、灵活、洋葱模型中间件”为核心优势，彻底解决了Express回调嵌套的问题，成为现代Node.js后端开发的主流选择之一。本系列教程将从项目搭建开始，逐步深入Koa的核心特性与实战开发。本文作为开篇，聚焦“从零创建Koa项目”，涵盖环境准备、项目初始化、核心代码编写及基础调试的完整流程。

一、先搞懂：为什么选择Koa？

在动手创建项目前，先明确Koa的核心价值，避免盲目跟风技术选型：

• 洋葱模型 中间件：中间件按“请求进入→内层中间件执行→响应返回”的顺序执行，支持请求与响应阶段的双向处理，轻松实现日志记录、权限校验等通用功能。
• 原生支持async/await：从根源上解决回调地狱问题，代码逻辑更清晰，错误捕获更便捷。
• 轻量无内置：仅保留核心HTTP封装，路由、静态资源等功能通过中间件扩展，按需引入避免冗余。
• 良好的生态兼容：与Express的中间件生态部分兼容，同时拥有专属的高质量中间件库（如koa-router、koa-static）。

提示：Koa 2.x版本需Node.js 7.6.0及以上支持（推荐使用Node.js 14+ LTS版本），确保后续环境满足该要求。

二、环境准备：安装Node.js与npm

Koa基于Node.js运行，需先完成Node.js与包管理工具npm的安装。推荐使用nvm（Node版本管理器）安装，便于灵活切换Node版本。

1. 安装nvm（推荐，Linux/macOS）

nvm可快速安装、切换不同版本的Node.js，避免权限问题与版本冲突：

# 1. 下载并安装nvm（官方脚本）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# 或使用wget
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash# 2. 激活nvm（关闭终端重新打开，或执行以下命令）
source ~/.bashrc  # bash终端
# 若为zsh终端，执行 source ~/.zshrc# 3. 验证nvm安装成功
nvm --version  # 输出nvm版本号即正常

2. 安装Node.js（LTS版本）

通过nvm安装长期支持版（LTS）Node.js，稳定性更有保障：

# 1. 安装最新LTS版本Node.js
nvm install --lts# 2. 设为默认版本（后续终端默认使用该版本）
nvm alias default lts/*# 3. 验证Node.js与npm安装成功
node -v  # 输出Node.js版本（如v20.17.0）
npm -v   # 输出npm版本（如10.8.1）

3. Windows环境补充

Windows用户可直接下载Node.js安装包：

1. 访问Node.js官网（https://nodejs.org/），下载“LTS”版本安装包。
2. 双击安装，勾选“Add to PATH”选项，完成后打开命令提示符（CMD）或PowerShell，执行node -v验证。

三、核心步骤：创建Koa项目

从项目初始化到启动服务，共4个核心步骤，所有操作在终端/命令行中完成。

1. 初始化npm项目

先创建项目目录，再通过npm初始化生成package.json（项目配置文件，记录依赖、脚本等信息）：

# 1. 创建项目目录（自定义目录名，如koa-demo）
mkdir koa-demo && cd koa-demo# 2. 初始化npm项目（-y表示默认配置，无需交互）
npm init -y

执行后，项目目录下会生成package.json文件，核心内容如下（可后续手动修改）：

{"name": "koa-demo","version": "1.0.0","description": "","main": "index.js",  // 项目入口文件（后续需改为app.js）"scripts": {"test": "echo "Error: no test specified" && exit 1"},"keywords": [],"author": "","license": "ISC"
}

2. 安装Koa核心依赖

通过npm安装Koa（核心框架），安装时会自动将依赖记录到package.json的dependencies中：

# 安装Koa（默认安装最新稳定版）
npm install koa

安装完成后，项目目录会新增node_modules（依赖包存放目录）和package-lock.json（依赖版本锁定文件），无需手动修改这两个文件。

3. 编写核心入口文件（app.js）

创建Koa项目的核心文件app.js，实现“启动服务+响应请求”的基础功能，同时演示Koa的洋葱模型中间件：

# 1. 创建并编辑app.js（使用nano或任意编辑器，如VS Code）
# 终端命令（Linux/macOS）：
nano app.js# Windows命令（CMD）：
notepad app.js

在app.js中写入以下代码，代码中包含详细注释：

// 1. 引入Koa模块（CommonJS规范，Node.js默认支持）
const Koa = require('koa');// 2. 创建Koa应用实例
const app = new Koa();// 3. 定义端口（推荐3000，避免与系统端口冲突）
const port = 3000;// 4. 中间件1：演示洋葱模型的“请求进入”阶段
app.use(async (ctx, next) => {console.log('中间件1：请求开始 - 记录时间');const start = Date.now();  // 记录请求开始时间// 调用next()，进入下一个中间件（核心：洋葱模型的“进入”环节）await next();// 下一个中间件执行完成后，回到这里（洋葱模型的“返回”环节）const end = Date.now();console.log(`中间件1：请求结束 - 耗时${end - start}ms`);
});// 5. 中间件2：核心业务逻辑（处理请求并返回响应）
app.use(async (ctx) => {console.log('中间件2：处理请求');// ctx是Koa的核心上下文对象，包含请求（ctx.request）和响应（ctx.response）信息ctx.status = 200;  // 设置响应状态码（200表示成功）ctx.type = 'text/html';  // 设置响应内容类型ctx.body = ``;  // 设置响应内容（即返回给浏览器的内容）
});// 6. 启动Koa服务，监听指定端口
app.listen(port, () => {console.log(`Koa服务已启动，访问地址：http://localhost:${port}`);
});

关键理解：洋葱模型中间件的执行顺序是“中间件1进入→中间件2执行→中间件1返回”，通过await next()实现流程跳转，这是Koa与其他框架的核心区别。

4. 启动Koa服务并验证

通过Node.js执行入口文件，启动服务后在浏览器验证效果：

# 1. 启动服务（执行app.js）
node app.js# 2. 终端输出以下内容，说明服务启动成功
Koa服务已启动，访问地址：http://localhost:3000

验证步骤：

1. 打开本地浏览器，输入http://localhost:3000，若看到“Hello Koa!”页面，说明响应正常。
2. 回到终端，可看到中间件执行日志（印证洋葱模型）： 中间件1：请求开始 - 记录时间 `` 中间件2：处理请求 ``中间件1：请求结束 - 耗时XXms
3. 停止服务：在终端按Ctrl+C即可终止服务。

四、优化开发体验：配置热重载（nodemon）

每次修改代码后，都需要手动重启服务才能生效，效率极低。通过nodemon工具可实现“代码修改后自动重启服务”，提升开发效率。

1. 安装nodemon（全局安装）

# 全局安装nodemon（一次安装，所有项目可用）
sudo npm install -g nodemon  # Linux/macOS需加sudo获取权限
# Windows系统直接执行：npm install -g nodemon

2. 用nodemon启动服务

# 替换node命令，用nodemon启动
nodemon app.js

测试热重载：修改app.js中ctx.body的内容（如将“Hello Koa!”改为“Hello Koa 2.0!”），保存后无需重启服务，刷新浏览器即可看到修改后的效果。

3. 配置npm脚本（简化命令）

修改package.json的scripts字段，将启动命令简化为npm run dev：

{"scripts": {"dev": "nodemon app.js",  // 新增：用nodemon启动服务"start": "node app.js",   // 新增：生产环境启动命令（无热重载）"test": "echo "Error: no test specified" && exit 1"}
}

配置后，启动服务的命令简化为：

# 开发环境启动（热重载）
npm run dev# 生产环境启动（无热重载，稳定）
npm run start

五、拓展：实现基础功能（响应JSON与请求参数获取）

在基础项目上，补充开发中常用的“响应JSON数据”和“获取请求参数”功能，完善项目实用性。

1. 响应JSON数据（接口开发常用）

修改app.js，新增一个中间件处理JSON响应：

// 在中间件1之后添加以下代码
app.use(async (ctx, next) => {// 匹配请求路径：/api/userif (ctx.path === '/api/user') {ctx.status = 200;ctx.type = 'application/json';  // 响应类型设为JSONctx.body = {code: 200,message: 'success',data: {id: 1,name: 'Koa User',age: 25}};return;  // 终止后续中间件执行}await next();  // 非/api/user路径，进入下一个中间件
});

验证：启动服务后，访问http://localhost:3000/api/user，浏览器会返回JSON格式数据。

2. 获取请求参数（query与params）

Koa的ctx.query可获取URL查询参数（如?id=1），结合后续路由中间件可获取路径参数（如/user/1），这里先实现查询参数获取：

// 在JSON响应中间件后添加
app.use(async (ctx) => {// 获取查询参数：http://localhost:3000/user?id=1&name=testconst { id, name } = ctx.query;ctx.body = `请求参数id: ${id || '无'}name: ${name || '无'}`;
});

验证：访问http://localhost:3000/user?id=1&name=koa，页面会显示对应的参数值。

六、项目目录结构说明（规范）

当前基础项目的目录结构如下，后续开发需按此规范扩展：

koa-demo/                  # 项目根目录
├── node_modules/          # 依赖包目录（自动生成）
├── app.js                 # 项目入口文件
├── package.json           # 项目配置文件
└── package-lock.json      # 依赖版本锁定文件（自动生成）

后续扩展方向：新增routes/（路由目录）、middleware/（自定义中间件目录）、controller/（业务逻辑目录），实现分层开发。

七、总结与后续预告

本文通过“环境准备→项目初始化→核心代码编写→开发优化”的流程，完成了Koa项目的基础搭建，核心知识点包括：

• Koa的核心优势与洋葱模型中间件的执行逻辑。
• 通过npm init和npm install koa初始化项目。
• 使用nodemon实现热重载，提升开发效率。
• 基础功能：响应HTML、JSON数据，获取请求参数。

如果在项目创建过程中遇到版本冲突、端口占用等问题，欢迎在评论区留言讨论。