CLI 工具

CLI 是什么

NestJS CLI 是一个命令行工具，帮你快速创建项目、生成代码文件、编译和运行应用。你可以把它理解成一个”脚手架工人”，帮你把重复的体力活全干了。

安装

全局安装：

npm install -g @nestjs/cli

安装后就能用 nest 命令了。

查看所有可用命令：

nest --help

查看某个命令的详细帮助：

nest generate --help

创建项目

用 nest new 创建一个新项目：

nest new my-nest-project

这条命令会：

• 创建一个以项目名命名的文件夹
• 生成完整的配置文件（package.json、tsconfig.json、nest-cli.json 等）
• 创建 src/ 目录（源代码）和 test/ 目录（测试）
• 初始化一个可运行的最小应用

创建完成后：

cd my-nest-project
npm run start:dev

打开浏览器访问 http://localhost:3000，就能看到应用跑起来了。改代码会自动重新编译和加载。

常用选项

nest new my-project --skip-git        # 跳过 git 初始化
nest new my-project --skip-install    # 跳过依赖安装
nest new my-project -p pnpm           # 指定包管理器（npm/yarn/pnpm）
nest new my-project -l JS             # 用 JavaScript 而非 TypeScript
nest new my-project --strict          # 开启严格 TypeScript 模式
nest new my-project -d                # 干跑模式，只报告不实际创建文件

生成代码

nest generate（简写 nest g）是最常用的命令。它能帮你生成各种代码文件，不用手动创建。

命令格式

nest generate <schematic> <name> [options]
nest g <schematic> <name> [options]

可用的 Schematic

名称	别名	生成什么
module	mo	模块
controller	co	控制器
service	s	服务
class	cl	类
decorator	d	装饰器
filter	f	异常过滤器
guard	gu	守卫
interceptor	itc	拦截器
middleware	mi	中间件
pipe	pi	管道
gateway	ga	WebSocket 网关
resolver	r	GraphQL 解析器
provider	pr	Provider
interface	itf	接口
resource	res	完整的 CRUD 资源

使用示例

# 生成一个模块
nest g mo cats

# 生成一个控制器（在 cats 模块下）
nest g co cats

# 生成一个服务
nest g s cats

# 生成一个守卫
nest g gu auth

# 生成一个完整的 CRUD 资源（包含模块、控制器、服务、DTO、测试）
nest g res users

生成选项

nest g co cats --flat       # 不创建子目录，直接放在当前目录
nest g co cats --no-spec    # 不生成测试文件
nest g co cats -p my-app    # 指定项目（monorepo 模式下用）

构建和运行

构建

nest build [name]

默认用 tsc 编译。编译输出到 dist/ 目录。

常用选项：

nest build --watch          # 监听模式，改代码自动编译
nest build -b swc           # 用 SWC 编译（比 tsc 快 10 倍）
nest build -b webpack       # 用 webpack 打包
nest build --all            # 构建 monorepo 中所有项目
nest build --type-check     # 用 SWC 时开启类型检查

运行

nest start [name]

nest start 会先编译，再运行。常用组合：

nest start                  # 编译并运行
nest start --watch          # 监听模式运行（开发用）
nest start --debug --watch  # 调试模式运行

package.json 脚本

项目创建后，package.json 里已经预设好了脚本：

{
  "scripts": {
    "build": "nest build",
    "start": "nest start",
    "start:dev": "nest start --watch",
    "start:debug": "nest start --debug --watch",
    "format": "prettier --write \"src/**/*.ts\"",
    "lint": "eslint \"{src,apps,libs,test}/**/*.ts\"",
    "test": "jest",
    "test:watch": "jest --watch",
    "test:cov": "jest --coverage"
  }
}

推荐用 npm run 来执行构建和启动命令，这样用的是项目本地安装的 CLI 版本，团队所有人用的版本一致。

查看项目信息

nest info

会显示 Node.js 版本、NestJS 各包的版本等信息，提 bug 的时候很有用。

nest-cli.json 配置文件

每个 NestJS 项目根目录都有一个 nest-cli.json，存放 CLI 的配置。

基本结构

{
  "$schema": "https://json.schemastore.org/nest-cli",
  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": {
    "deleteOutDir": true,
    "assets": ["**/*.graphql"],
    "watchAssets": true
  }
}

几个关键配置：

配置项	说明
sourceRoot	源代码根目录
compilerOptions.deleteOutDir	编译前是否删除输出目录
compilerOptions.assets	需要复制的非 TS 文件（如 .graphql）
compilerOptions.watchAssets	是否监听非 TS 文件变化
compilerOptions.builder	编译器选择：tsc、swc 或 webpack
compilerOptions.plugins	编译器插件（如 Swagger 插件）

编译器插件

在 compilerOptions.plugins 里可以配置编译器插件：

{
  "compilerOptions": {
    "plugins": ["@nestjs/swagger"]
  }
}

@nestjs/swagger 插件能自动从 DTO 的类型和 class-validator 装饰器中提取 Swagger 文档信息，省去手写 @ApiProperty() 参数的工作。

资源配置

assets 用来指定需要复制到输出目录的非 TypeScript 文件：

{
  "compilerOptions": {
    "assets": [
      "**/*.graphql",
      "**/*.proto"
    ],
    "watchAssets": true
  }
}

也可以更精细地控制：

{
  "compilerOptions": {
    "assets": [
      {
        "include": "**/*.graphql",
        "exclude": "**/omitted.graphql",
        "outDir": "dist/assets",
        "watchAssets": true
      }
    ]
  }
}

Monorepo 模式

NestJS 支持两种项目组织方式：

• 标准模式：一个项目一个文件夹，各自独立
• Monorepo 模式：多个项目放在同一个仓库里

什么时候用 Monorepo？

场景	推荐模式
单个应用	标准模式
多个应用共享代码	Monorepo
需要共享 ESLint/Prettier 配置	Monorepo
需要集成测试多个应用	Monorepo

从标准模式切换到 Monorepo

在已有项目里添加一个新应用，就自动转成 Monorepo 了：

nest generate app my-app

转换后的目录结构：

apps/
  my-project/       # 原来的项目（变成默认项目）
    src/
    tsconfig.app.json
  my-app/           # 新加的应用
    src/
    tsconfig.app.json
nest-cli.json
package.json
tsconfig.json

操作指定项目

nest build my-app       # 构建指定项目
nest start my-app       # 运行指定项目
nest build --all        # 构建所有项目

不指定项目名的话，默认操作 nest-cli.json 里 "root" 指向的那个项目。

库（Library）

库是 Monorepo 模式下的概念。库不能独立运行，它是一组可复用的模块、服务、控制器等，被应用引用。

创建库

nest generate library my-library

会提示你输入前缀（默认 @app），然后在 libs/ 目录下生成库的代码：

libs/
  my-library/
    src/
      index.ts
      my-library.module.ts
      my-library.service.ts
    tsconfig.lib.json

使用库

在应用里导入库模块，用前缀 + 库名作为路径：

import { Module } from '@nestjs/common';
import { MyLibraryModule } from '@app/my-library';

@Module({
  imports: [MyLibraryModule],
})
export class AppModule {}

NestJS 会自动在 tsconfig.json 里配置路径映射：

{
  "paths": {
    "@app/my-library": ["libs/my-library/src"],
    "@app/my-library/*": ["libs/my-library/src/*"]
  }
}

常用命令速查

# 项目创建
nest new my-project              # 创建新项目
nest new my-project -p pnpm      # 用 pnpm 管理依赖

# 代码生成
nest g mo cats                   # 生成模块
nest g co cats                   # 生成控制器
nest g s cats                    # 生成服务
nest g gu auth                   # 生成守卫
nest g pi validation             # 生成管道
nest g itc logging               # 生成拦截器
nest g f http-exception          # 生成异常过滤器
nest g ga chat                   # 生成 WebSocket 网关
nest g res users                 # 生成完整 CRUD 资源

# 构建运行
nest build                       # 编译
nest build --watch               # 监听模式编译
nest build -b swc                # 用 SWC 编译
nest start                       # 运行
nest start --watch               # 开发模式运行
nest start --debug --watch       # 调试模式运行

# Monorepo
nest generate app api-gateway    # 添加新应用
nest generate library shared     # 添加库
nest build --all                 # 构建所有项目

# 其他
nest info                        # 查看版本信息
nest --help                      # 查看所有命令
nest g --help                    # 查看生成命令帮助

小结

本章介绍了 NestJS CLI 的核心功能：

• nest new 创建项目，自带完整的配置文件和目录结构
• nest generate 生成各种代码文件，不用手写样板代码
• nest build 编译项目，支持 tsc、SWC、webpack 三种编译器
• nest start 编译并运行，支持监听和调试模式
• Monorepo 模式可以在一个仓库里管理多个应用和库
• 库（Library）是 Monorepo 内部共享代码的方式
• nest-cli.json 控制编译选项、资源配置等

CLI 是 NestJS 开发的好帮手。熟练使用这些命令，能省下大量写样板代码的时间。