【NestJS】02 NestJS CLI 全功能指南

作为 NestJS 开发者，你有没有过这样的经历？
手动创建users模块 → 新建users.controller.ts→ 复制粘贴基础路由 → 修改类名 → 注册到模块……一套操作下来，10 分钟没了，还容易写错@Controller的前缀！😩

别慌！NestJS CLI就是来拯救你的——它是 Nest 生态的“效率引擎”，用命令行搞定 90%的重复工作：项目初始化、组件生成、开发调试、构建部署，全流程自动化！

今天这篇指南，从基础命令到高级玩法，把 NestJS CLI 的所有功能讲透，帮你彻底告别“手动搬砖”的日子～

一、先搞懂：NestJS CLI 到底是什么？#

NestJS CLI 不是简单的“脚手架工具”，而是全生命周期开发平台——它的核心设计哲学是「约定优于配置」：

生成的Module会自动注册到AppModule；
生成的Controller会自动加路由前缀；
自动生成测试文件（可选）；
统一代码结构，避免团队成员“各自为战”。

简单说：CLI 帮你做“重复的事”，你只需要做“核心的事”（比如写业务逻辑）。

二、基础命令：从 0 到 1 创建 Nest 项目#

2.1 初始化项目：一行命令建完整框架#

最常用的命令就是nest new——用它创建项目，比手动建文件夹快 10 倍！

示例：创建基础项目#

1
nest new my-nest-app  # 创建名为my-nest-app的项目

运行后，CLI 会问你选包管理器（npm/yarn/pnpm），选好后自动完成：

下载依赖；
生成标准化目录结构；
初始化 Git 仓库（可选）。

生成的项目结构长这样：

1
my-nest-app/
2
├── src/                # 源码根目录
3
│   ├── app.controller.ts  # 默认控制器（处理请求）
4
│   ├── app.service.ts     # 默认服务（业务逻辑）
5
│   ├── app.module.ts      # 根模块（组织所有组件）
6
│   └── main.ts            # 入口文件（启动应用）
7
├── test/               # 测试目录
8
├── nest-cli.json       # CLI配置文件（核心！）
9
└── package.json        # 依赖配置

2.2 核心生成命令：快速创建组件#

NestJS 的核心组件（Module/Controller/Service 等），都能通过nest generate（缩写nest g）命令生成！

高频命令清单（必背）#

组件类型	命令（完整）	命令（缩写）	说明
模块	`nest generate module users`	`nest g mo users`	创建用户模块
控制器	`nest generate controller users`	`nest g co users`	创建用户控制器（带路由）
服务	`nest generate service users`	`nest g s users`	创建用户服务（业务逻辑）
中间件	`nest generate middleware logger`	`nest g mi logger`	创建日志中间件
守卫	`nest generate guard auth`	`nest g gu auth`	创建权限守卫
管道	`nest generate pipe validation`	`nest g pi validation`	创建参数验证管道

示例：生成用户模块+控制器+服务#

1
# 1. 创建用户模块（自动生成UsersModule）
2
nest g mo users
3

4
# 2. 创建用户控制器（自动注册到UsersModule）
5
nest g co users --no-spec  # --no-spec：不生成测试文件
6

7
# 3. 创建用户服务（自动注册到UsersModule）
8
nest g s users --no-spec

生成的users.controller.ts会自动带基础路由：

1
import { Controller, Get } from '@nestjs/common'
2

3
@Controller('users') // 路由前缀：/users
4
export class UsersController {
5
  @Get() // 处理GET /users请求
6
  findAll() {
7
    return 'This action returns all users'
8
  }
9
}

三、nest-cli.json：定制你的 CLI 行为#

nest-cli.json 是 CLI 的“配置中心”，你可以通过它调整生成规则、编译器选项、静态资源处理。

3.1 核心配置项解析#

看一个常用配置示例（注释版）：

1
{
2
  "$schema": "https://json.schemastore.org/nest-cli", // 配置schema（语法提示）
3
  "collection": "@nestjs/schematics", // 使用Nest官方Schematics（生成器模板）
4
  "sourceRoot": "src", // 源码根目录（默认是src）
5
  "compilerOptions": {
6
    "deleteOutDir": true, // 构建前删除dist目录（避免旧文件缓存）
7
    "assets": [
8
      // 处理静态资源（比如.env、.json）
9
      {
10
        "include": "**/*.env", // 包含所有.env文件
11
        "outDir": "./dist", // 复制到dist目录
12
        "watchAssets": true // 监视文件变化（开发模式下自动同步）
13
      }
14
    ],
15
    "plugins": [
16
      // 集成第三方插件（比如Swagger）
17
      {
18
        "name": "@nestjs/swagger",
19
        "options": {
20
          "dtoKeyOfComment": "description", // 用DTO的注释生成Swagger描述
21
          "controllerKeyOfComment": "summary" // 用Controller的注释生成Swagger摘要
22
        }
23
      }
24
    ]
25
  },
26
  "generateOptions": {
27
    "spec": true, // 默认生成测试文件（.spec.ts）
28
    "flat": false // 生成组件时创建目录（比如users模块会生成users文件夹）
29
  }
30
}

3.2 实用配置技巧#

关闭测试文件：如果不想生成.spec.ts，可以加--no-spec参数，或修改generateOptions.spec: false；
扁平化结构：如果不想生成组件目录（比如users.controller.ts直接放在src下），加--flat参数；
处理静态资源：如果有.env、.proto等文件需要打包到 dist，一定要配置assets！

四、高级玩法：让 CLI 更懂你的团队#

4.1 自定义生成模板：统一代码风格#

如果你的团队有统一代码规范（比如 Controller 必须带 Swagger 装饰器），可以自定义生成模板！

步骤 1：创建自定义模板#

新建模板目录（比如~/.nest-templates/rest-controller）；
写模板文件__name__.controller.ts（用 EJS 语法）：

1
import { Controller, Get, Post, Body } from '@nestjs/common';
2
import { ApiTags, ApiOperation } from '@nestjs/swagger'; // 团队要求加Swagger
3

4
@ApiTags('<%= dasherize(name) %>')  // 自动生成API标签（比如users→"users"）
5
@Controller('<%= dasherize(name) %>')  // 自动加路由前缀
6
export class <%= classify(name) %>Controller {  // 自动生成类名（比如users→UsersController）
7
  @Get()
8
  @ApiOperation({ summary: '查询所有<%= name %>' })  // 自动加接口描述
9
  findAll() {
10
    return `返回所有<%= name %>`;
11
  }
12

13
  @Post()
14
  @ApiOperation({ summary: '创建<%= name %>' })
15
  create(@Body() data: any) {
16
    return `创建${name}成功`;
17
  }
18
}

步骤 2：用自定义模板生成组件#

1
nest g co users --template rest-controller  # 使用自定义模板生成控制器

生成的users.controller.ts会自动带 Swagger 装饰器，不用手动写！是不是超省心？😎

4.2 多项目工作区（Monorepo）：管理多个应用#

如果你的项目是微服务架构（比如有api和admin两个应用），可以用 CLI 的Monorepo模式：

步骤 1：创建 Monorepo 项目#

1
nest new my-monorepo --package-manager pnpm  # 用pnpm管理依赖（推荐）

步骤 2：添加子项目#

1
# 添加API应用（处理接口）
2
nest generate app api
3

4
# 添加Admin应用（后台管理）
5
nest generate app admin
6

7
# 添加共享库（比如通用工具）
8
nest generate lib shared

步骤 3：配置 nest-cli.json#

1
{
2
  "monorepo": true, // 开启Monorepo模式
3
  "projects": {
4
    "api": {
5
      "type": "application", // 应用类型
6
      "root": "apps/api", // 根目录
7
      "sourceRoot": "apps/api/src" // 源码目录
8
    },
9
    "admin": {
10
      "type": "application",
11
      "root": "apps/admin"
12
    },
13
    "shared": {
14
      "type": "library", // 库类型（可共享）
15
      "root": "libs/shared"
16
    }
17
  }
18
}

五、开发最佳实践：用 CLI 提升效率#

5.1 标准开发流程：从功能到接口#

用 CLI 开发新功能的标准步骤：

建模块：nest g mo features/users（用户模块）；
建实体：nest g class features/users/entities/user.entity（对应数据库表）；
建 DTO：nest g class features/users/dto/create-user.dto（创建用户的参数）；
建服务：nest g s features/users/services/users（业务逻辑）；
建控制器：nest g co features/users/controllers/users（处理请求）。

5.2 调试技巧：用 VSCode 断点调试#

想调试 Nest 应用？只需两步：

启动开发服务器（带调试模式）：

1
nest start --debug --watch  # --watch：热重载；--debug：开启调试

配置 VSCode 的launch.json：

1
{
2
  "version": "0.2.0",
3
  "configurations": [
4
    {
5
      "type": "node",
6
      "request": "launch",
7
      "name": "Debug Nest",
8
      "runtimeExecutable": "nest",
9
      "args": ["start", "--debug", "--watch"],
10
      "console": "integratedTerminal",
11
      "restart": true, // 代码变化时自动重启
12
      "autoAttachChildProcesses": true // 自动附加子进程
13
    }
14
  ]
15
}

按F5启动调试，就能在 Controller/Service 里加断点，一步步看代码执行流程～

六、常见问题：踩过的坑都帮你填了#

6.1 全局安装 CLI 报错（权限问题）#

如果安装时遇到EACCES: permission denied：

1
# 解决方案1：用--unsafe-perm选项
2
npm install -g @nestjs/cli --unsafe-perm
3

4
# 解决方案2：用nvm管理Node版本（推荐）
5
nvm install 18  # 安装Node 18
6
nvm use 18       # 使用Node 18
7
npm install -g @nestjs/cli

6.2 生成器找不到路径#

如果生成组件时提示“路径不存在”：

1
nest g mo modules/users  # 报错：Path "modules/users" does not exist

解决方案：

确保路径在sourceRoot下（默认是src），比如用src/modules/users：

1
nest g mo src/modules/users

或者修改nest-cli.json的sourceRoot为src（默认就是，不用改）。

七、写在最后：CLI 是 Nest 开发的“效率引擎”#

NestJS CLI 不是“可选工具”，而是“必学技能”——它能帮你：

减少重复劳动（不用手动创建文件、注册模块）；
统一代码风格（团队成员用同一套模板）；
提升开发效率（把时间放在核心业务上）。

如果你是 Nest 新手，先掌握nest new、nest g mo、nest g co、nest g s这几个基础命令；
如果是老鸟，可以尝试自定义模板、开发 Schematics，让 CLI 更符合团队需求。

最后送你一句话：用 CLI 少写一行代码，就多一份时间去喝咖啡～ ☕

（注：文中命令基于 Nest CLI v10.x，不同版本可能有差异，建议用nest --version检查当前版本～）

音乐

音乐