企业官网建设流程全解析

Umi 本地开发环境搭建：Node.js 安装、pnpm 依赖管理与 IDE 选择

【免费下载链接】umiA framework in react community ✨项目地址: https://gitcode.com/GitHub_Trending/um/umi

本文基于 Umi 仓库官方文档 Development Environment，完整讲解从零搭建 Umi.js 项目本地开发环境的标准流程：安装 Node.js 并管理其版本、安装官方推荐的 pnpm 包管理器、选择合适的 IDE，以及环境就绪后如何一键创建并启动第一个 Umi 项目。读完本文，你可以按照可复制、可验证的命令序列完成环境准备，并理解 Umi 仓库自身对 Node 与 pnpm 版本约束的实现依据。

环境与适用场景

这篇指南面向两类读者：

• 准备使用 Umi 开发业务前端项目，需要先把本地基础环境搭好；
• 希望了解 Umi 官方为何强制使用 pnpm、为何要求特定 Node 版本，并能从源码中找到这些约束的依据。

需要说明的版本口径：该文档建议Node.js 版本高于 18（文档译制时间为 2024-03-17）；而仓库中更新的 快速上手 文档已建议 Node 22 及以上。从当前仓库的 根 package.json 可以看到，Umi 仓库自身声明的运行环境为engines: { "node": ">=14", "pnpm": "^8.15.9" }，并通过packageManager: "pnpm@8.15.9"与volta字段进一步锁定工具链版本。也就是说，对 Umi 使用者而言 Node 18 是当时文档给出的起步线，而贡献代码到 Umi 仓库本身时，pnpm 8.15.9 是仓库明确要求的版本。

安装 Node.js 并管理版本

Umi.js 开发依赖 Node.js 运行时，需要确保本机已安装 Node.js 且版本满足要求。文档推荐按平台选择版本管理工具：

• macOS / Linux 用户推荐nvm；
• Windows 用户推荐nvm-windows。

以下命令以 macOS 或 Linux 环境为例，先用 nvm 安装管理器本身：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash nvm -v 0.39.1

确认 nvm 可用后，安装并切换到 Node.js 18：

nvm install 18 nvm use 18

安装完成后，用node -v验证版本是否符合预期（文档示例输出为v18.14.0，具体小版本取决于 nvm 拉取的最新 18.x）：

node -v v18.14.0

使用 nvm 的好处是可以在不同项目间自由切换 Node 大版本，避免全局环境污染——这对同时维护 Umi 3/4 项目或使用不同 Node 版本的其他框架的团队尤其有用。

安装并验证 pnpm 依赖管理

安装 Node 后，npm 随附可用，但Umi 官方推荐使用 pnpm 作为依赖管理工具。安装命令：

curl -fsSL https://get.pnpm.io/install.sh | sh -

安装完成后验证：

pnpm -v 7.3.0

注意：文档中7.3.0是该文档写作时的验证示例。若用于贡献 Umi 仓库本身，应安装 pnpm 8.15.9（仓库packageManager字段指定）。

为什么 Umi 坚持 pnpm：来自仓库源码的依据

这不是随口推荐，在仓库内可以找到多处实现级证据：

1. 安装器强制拦截：根 package.json 中配置了"preinstall": "npx only-allow pnpm"，意味着如果尝试用 npm 或 yarn 在 Umi 仓库内执行 install，预安装脚本会直接报错退出，从机制上保证 monorepo 只能走 pnpm。
2. workspace 协议依赖：根 package.json 的devDependencies中大量使用"@umijs/bundler-webpack": "workspace:*"、"umi": "workspace:*"等workspace:协议引用，配合 pnpm-workspace.yaml 中声明的包范围（packages/*、examples/*、libs/*、codemod、copilot、did-you-know、scripts、ui、docs），把整个 Umi 工程组织成一个 pnpm monorepo。workspace:*是 pnpm/yarn 系工具的原生能力，npm 不直接支持这种本地包链接方式。
3. pnpm 专属配置：package.json的pnpm字段中配置了peerDependencyRules.ignoreMissing（豁免 react、antd、webpack 等可选 peer 依赖告警）、overrides（锁定@parcel/watcher、统一browserslist版本）以及patchedDependencies（对webpack@5.105.4应用 patches/webpack@5.105.4.patch 补丁）。这些配置只有在 pnpm 下才会生效，进一步印证 pnpm 是 Umi 工具链的既定前提。
4. 依赖安装后补丁：postinstall脚本会执行umi-scripts postinstall（见 scripts/postinstall.ts），在安装完成后对@vercel/ncc的缓存文件打补丁，修复其在打包纯 ESM 包时的兼容问题——这也是选择 pnpm 精确依赖布局后才能稳定工作的配套脚本。

从源码结构看，pnpm 带来的硬链接式全局存储、严格依赖隔离与 workspace 协议，正是 Umi 这种包含数十个子包的 monorepo 能够快速安装、稳定构建的基础。

选择 IDE

安装好 Node.js 与 pnpm（或其他依赖管理工具）之后，需要选择一个顺手的 IDE 或编辑器编写代码。文档给出了如下候选清单：

1. Visual Studio Code（推荐）
2. WebStorm（推荐）
3. IntelliJ IDEA
4. Sublime Text
5. Atom

其中 VS Code 与 WebStorm 被官方标注为推荐项。值得注意的是，Umi 仓库本身为 WebStorm 用户提供了额外的开发体验支持：根 package.json 中定义了"setup:webstorm": "umi-scripts setupWebStorm"脚本，对应的实现为 scripts/setupWebStorm.ts。从仓库脚本结构看，官方为 IDE 开发者配置了专门的初始化流程，这也侧面说明 WebStorm 是 Umi 团队认可并持续维护的开发环境之一。

环境就绪：创建并启动第一个项目

完成 Node.js 与 pnpm 安装、IDE 选型后，本地环境即已就绪。按照 官方脚手架（boilerplate）文档，可以用一条命令创建 Umi 项目：

# 交互式：在向导中输入文件夹名称 pnpm create umi # 非交互：在当前目录的 my-umi-app 文件夹下创建项目 pnpm create umi my-umi-app

该命令会安装create-umi脚手架并自动运行，运行过程会依次让你选择：

1. Pick Npm Client——选择 Node 依赖管理工具，可选 npm / cnpm / tnpm / yarn / pnpm，其中pnpm 为 Umi 官方推荐，与本文前面的环境准备结论一致；
2. Pick Npm Registry——选择 npm 源。

选择完成后会自动生成一个最基础的 Umi 项目，并按所选客户端与镜像源安装依赖，生成的目录结构为：

. ├── package.json ├── pnpm-lock.yaml ├── src │ ├── assets │ │ └── yay.jpg │ ├── layouts │ │ ├── index.less │ │ └── index.tsx │ └── pages │ ├── docs.tsx │ └── index.tsx ├── tsconfig.json └── typings.d.ts

脚手架安装成功后会自动执行umi setup完成文件预处理（生成约定式运行时文件等）。更多创建参数（如--template从模板创建、--no-git、--no-install）与启动（pnpm dev）、构建（pnpm build，产物输出到./dist）的完整流程，可继续阅读 快速上手 与 boilerplate 文档。

环境准备速查清单

几点适用前提与限制说明：

• 文档给出的 Node 18 为最低建议线，node -v输出的小版本（如18.14.0）与pnpm -v输出的7.3.0均为文档写作时的示例值，实际以你安装时的最新可用版本为准；
• 若你的目标是在 Umi 仓库内贡献代码，请以 根 package.json 中packageManager指定的 pnpm 8.15.9 为准，并遵守only-allow pnpm的安装约束；
• 国内网络环境建议在脚手架交互中选择 pnpm 配合国内镜像源，可显著提升依赖安装速度（快速上手 文档对此有明确建议）。

至此，一个可运行的 Umi 开发环境即搭建完成，可以进入后续的 目录结构、路由 等指南继续深入。

【免费下载链接】umiA framework in react community ✨项目地址: https://gitcode.com/GitHub_Trending/um/umi