---
sidebar_position: 1
---

# 命令

Modern.js 内置了一些命令，可以帮助你快速启动开发服务器、构建生产环境代码等。

通过本章节，你可以了解到 Modern.js 内置的命令有哪些，以及如何使用这些命令。

## modern dev

`modern dev` 命令用于启动一个本地开发服务器，对源代码进行开发环境编译。

```bash
Usage: modern dev [options]

Options:
  -e --entry <entry>    指定入口，只编译特定的页面
  -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
  -h, --help            显示命令帮助
  --analyze             分析构建产物体积，查看各个模块打包后的大小
  --web-only            仅启动 Web 服务
  --api-only            仅启动 API 接口服务
```

运行 `modern dev` 后，Modern.js 会监听源文件变化并进行模块热更新。

```bash
$ modern dev

info    Starting dev server...

  > Local:    http://localhost:8080/
  > Network:  http://192.168.0.1:8080/
```

### 编译部分页面

在多页面（MPA）项目中，可以添加 `--entry` 参数来指定编译其中的一个或多个页面。这样可以只编译项目中的部分代码，从而提升 dev 启动速度。

比如执行 `modern dev --entry`，在命令行界面中会展示入口选择框：

```bash
$ modern dev --entry

? 请选择需要构建的入口
❯ ◯ foo
  ◯ bar
  ◯ baz
```

比如选择 `foo` 入口，那么只有 `foo` 入口相关的代码会进行编译，其他页面的代码将不会参与构建。

### 通过参数指定页面

你也可以在 `--entry` 后面通过参数来指定页面名称，多个页面的名称使用逗号分隔。

```bash
# 编译 foo 页面
modern dev --entry foo

# 编译 foo 和 bar 页面
modern dev --entry foo,bar
```

## modern start

`modern start` 是 `modern dev` 命令的别名，两者的功能和用法完全一致。

## modern build

`modern build` 命令默认会在 `dist/` 目录下构建出可用于生产环境的产物。你可以通过修改配置 [`output.distPath`](/configure/app/output/dist-path) 指定产物的输出目录。

```bash
Usage: modern build [options]

Options:
  -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
  -h, --help  显示命令帮助
  --analyze   分析构建产物体积，查看各个模块打包后的大小
```

### 分析构建产物体积

执行 `npx modern build --analyze` 命令，可以在打包生产环境代码的同时，产出一个分析构建产物体积的 HTML 文件：

```
Bundle Analyzer saved report to /example/dist/report.html

info    Production file sizes:

  File                                      Size         Gzipped
  dist/static/js/lib-react.09721b5c.js      152.6 kB     49.0 kB
  dist/html/main/index.html                 5.8 kB       2.5 kB
  dist/static/js/main.3568a38e.js           3.5 kB       1.4 kB
  dist/static/css/main.03221f72.css         1.4 kB       741 B
```

手动在浏览器中打开上述 HTML 文件，可以看到打包产物的瓦片图，并进行包体积分析和优化：

<img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/mwa-build-analyze-8784f762c1ab0cb20935829d5f912c4c.png" />

> 该功能基于 [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) 实现。

## modern new

`modern new` 命令用于在已有项目中添加项目元素。

比如添加应用入口、启用一些可选功能如 Tailwind CSS、微前端开发模式等。

```bash
Usage: modern new [options]

Options:
  --config-file <configFile>  指定配置文件路径，可以为相对路径或绝对路径
  --lang <lang>          设置 new 命令执行语言(zh 或者 en)
  -d, --debug            开启 Debug 模式，打印调试日志信息 (default: false)
  -c, --config <config>  生成器运行默认配置(JSON 字符串)
  --dist-tag <tag>       生成器使用特殊的 npm Tag 版本
  --registry             生成器运行过程中定制 npm Registry
  -h, --help             显示命令帮助
```

### 添加入口

在 Modern.js 工程中，执行 `new` 命令添加入口的步骤如下：

```bash
$ npx modern new
? 请选择你想要的操作 创建工程元素
? 请选择创建元素类型 新建「应用入口」
? 请填写入口名称 entry
```

### 启用可选功能

在 Modern.js 工程中，执行 `new` 命令启用可选能力的步骤如下：

```bash
$ npx modern new
? 请选择你想要的操作 启用可选功能
? 请选择功能名称 (Use arrow keys)
❯ 启用 「Tailwind CSS」 支持
  启用「BFF」功能
  启用「微前端」模式
```

:::tip
`--config` 参数对应参数值需要使用 JSON 字符串。

pnpm 暂不支持使用 JSON 字符串作为参数值，可使用 `npm new` 开启相关功能。【[相关 Issue](https://github.com/pnpm/pnpm/issues/3876)】

:::

import ServeCommand from "@site-docs/components/serve-command";

<ServeCommand />

## modern upgrade

在项目根目录下执行命令 `npx modern upgrade`，会默认将当前执行命令项目的 `package.json` 中的 Modern.js 相关依赖更新至最新版本。

```bash
Usage: modern upgrade [options]

Options:
  -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
  --registry <registry>  定制 npm registry (default: "")
  -d,--debug             开启 Debug 模式，打印调试日志信息 (default: false)
  --cwd <cwd>            项目路径 (default: "")
  -h, --help             display help for command
```

## modern inspect

`modern inspect` 命令用于查看项目的 [Rsbuild 配置](https://rsbuild.dev/zh/config/index) 以及 webpack 或 Rspack 配置。

```bash
Usage: modern inspect [options]

Options:
  --env <env>           查看指定环境下的配置 (default: "development")
  --output <output>     指定在 dist 目录下输出的路径 (default: "./")
  --verbose             在结果中展示函数的完整内容
  -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
  -h, --help            显示命令帮助
```

在项目根目录下执行命令 `npx modern inspect` 后，会在项目的 `dist` 目录生成以下文件：

- `rsbuild.config.mjs`: 表示在构建时使用的 Rsbuild 配置。
- `webpack.config.web.mjs`: 表示在构建时使用的 webpack 配置。

```bash
➜ npx modern inspect

Inspect config succeed, open following files to view the content:

  - Rsbuild Config: /root/my-project/dist/rsbuild.config.mjs
  - Webpack Config (web): /root/my-project/dist/webpack.config.web.mjs
```

### 指定环境

默认情况下，inspect 命令会输出开发环境的配置，你可以添加 `--env production` 选项来输出生产环境的配置：

```bash
modern inspect --env production
```

### 完整内容

默认情况下，inspect 命令会省略配置对象中的函数内容，你可以添加 `--verbose` 选项来输出函数的完整内容：

```bash
modern inspect --verbose
```

### SSR 构建配置

如果项目开启了 SSR 能力，则在 `dist` 目录会另外生成一份 `webpack.config.node.mjs` 文件，对应 SSR 构建时的 webpack 配置。

```bash
➜ npx modern inspect

Inspect config succeed, open following files to view the content:

  - Rsbuild Config: /root/my-project/dist/rsbuild.config.mjs
  - Webpack Config (web): /root/my-project/dist/webpack.config.web.mjs
  - Webpack Config (node): /root/my-project/dist/webpack.config.node.mjs
```

import DeployCommand from "@site-docs/components/deploy-command";

<DeployCommand />
