> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# 版本升级


## 手动升级

Modern.js 所有的官方包使用**统一版本号**进行发布，因此升级时需要将所有 `@modern-js/**` 包的版本统一更新到目标版本。

### 升级步骤

1. **查看最新版本**

   你可以通过以下方式查看 Modern.js 的最新版本：

   - 访问 [npm](https://www.npmjs.com/package/@modern-js/app-tools) 查看 `@modern-js/app-tools` 的最新版本
   - 查看 [GitHub Releases](https://github.com/web-infra-dev/modern.js/releases)

根据官网 [Release Note](https://github.com/web-infra-dev/modern.js/releases)，开发者也可以手动将项目升级到想要的版本。

2. **更新 package.json**

   在项目的 `package.json` 中，将所有 `@modern-js/**` 包的版本更新到目标版本。例如：

   ```json title="package.json"
   {
     "dependencies": {
       "@modern-js/app-tools": "3.0.0",
       "@modern-js/runtime": "3.0.0"
     },
     "devDependencies": {
       "@modern-js/types": "3.0.0"
     }
   }
   ```

3. **重新安装依赖**

   更新完 `package.json` 后，重新安装依赖：


```sh [npm]
npm install
```

```sh [yarn]
yarn install
```

```sh [pnpm]
pnpm install
```

```sh [bun]
bun install
```

```sh [deno]
deno install
```

:::tip
当升级时，需要对 Modern.js 官方提供的所有包做统一升级，而不是升级单个依赖。确保所有 `@modern-js/**` 包的版本号保持一致。
:::

## 版本管理策略

在 Modern.js 项目中，我们推荐所有官方提供的依赖都使用固定版本号，不使用 `^` 或 `~` 进行范围声明。例如：

```json
{
  "dependencies": {
    "@modern-js/app-tools": "x.y.z"
  }
}
```

这样可以确保依赖的版本是完全确定的，从而保证构建的一致性和可预测性。

## 锁定子依赖

当项目某个子依赖出现问题，而 Modern.js 无法立即更新时，可以使用包管理器锁定子依赖版本。

### pnpm

对于使用 pnpm 的项目，请在**项目根目录**的 `package.json` 中添加以下配置，然后重新执行 `pnpm install`：

```json title="package.json"
{
  "pnpm": {
    "overrides": {
      "package-name": "^1.0.0"
    }
  }
}
```

### Yarn

对于使用 Yarn 的项目，请在**项目根目录**的 `package.json` 中添加以下配置，然后重新执行 `yarn install`：

```json title="package.json"
{
  "resolutions": {
    "package-name": "^1.0.0"
  }
}
```

### Npm

对于使用 Npm 的项目，请在**项目根目录**的 `package.json` 中添加以下配置，然后重新执行 `npm install`：

```json title="package.json"
{
  "overrides": {
    "package-name": "^1.0.0"
  }
}
```

:::info
对于 Monorepo 仓库，只能在项目根目录的 `package.json` 中锁定依赖版本，并且会影响 Monorepo 中的所有 package。

:::