Umi 脚手架实战指南：用 `pnpm create umi` 一键初始化 React 项目

Umi 脚手架实战指南：用pnpm create umi一键初始化 React 项目

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

本篇技术指南围绕 Umi 官方脚手架create-umi展开，讲解如何通过pnpm create umi命令在向导引导下快速创建标准 Umi 项目、选择 Npm 客户端与镜像源、理解生成后的目录结构，并结合仓库源码（packages/create-umi）剖析脚手架背后的交互流程、模板注入与依赖安装原理，帮助读者从"会用"进阶到"懂原理"。

一、脚手架是什么：一条命令完成项目初始化

Umi 官方提供了一个脚手架create-umi，用于快速生成标准化的 Umi 项目骨架。你只需要一条命令，向导就会自动完成"选目录 → 选模板 → 选包管理器 → 选镜像源 → 生成文件 → 安装依赖 → 初始化 Git"的全流程。

# 直接运行，向导会提示你输入目标文件夹名称 pnpm create umi # 一步到位：在当前目录的 my-umi-app 文件夹下创建项目 pnpm create umi my-umi-app

从源码实现看，pnpm create umi实际执行的是create-umi包（packages/create-umi/package.json 中bin字段指向bin/create-umi.js）。CLI 入口（packages/create-umi/src/cli.ts）解析命令行参数后，调用核心生成器 packages/create-umi/src/index.ts，最终把参数注入模板文件并渲染到目标目录。

运行后脚手架会依次询问两类问题，下面逐一说明。

二、向导选项一：Pick Npm Client（选择 Npm 客户端）

你可以从以下 5 个选项中挑选习惯的 Node 依赖管理工具：

源码中对应枚举定义（packages/create-umi/src/index.ts）：

enum ENpmClient { npm = 'npm', cnpm = 'cnpm', tnpm = 'tnpm', yarn = 'yarn', pnpm = 'pnpm', }

值得注意的工程细节：当选择pnpm时，脚手架会先探测本地 pnpm 版本（getPnpmVersion）：

• 若主版本为 7（且介于 7.0.0 与 7.13.5 之间），会在生成的.npmrc中写入strict-peer-dependencies=false，以抑制 pnpm v7 的 peer 依赖告警；
• 若主版本为 8 且版本号低于 8.7.0，由于 pnpm v8 默认按"最小版本"解析依赖，脚手架会改用pnpm up -L（installAndUpdateWithPnpm）把所有依赖升级到最新版，避免生成一个依赖过旧的锁文件；
• 若未安装 pnpm，脚手架会直接报错提示"Please install pnpm first"。

三、向导选项二：Pick Npm Registry（选择 Npm 源）

源码中两种 Registry 的完整地址定义在 packages/create-umi/src/template.ts：

export enum ERegistry { npm = 'https://registry.npmjs.com/', taobao = 'https://registry.npmmirror.com/', }

选择结果会写入生成项目的.npmrc文件，后续依赖安装与模板下载都基于该镜像源进行。国内开发者选择taobao通常能显著提升下载速度。

四、生成后的项目结构解析

选择完成后，脚手架会自动生成一个最基本的 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

对照仓库中的模板源文件 packages/create-umi/templates/app，可以看到各文件的实际作用：

• src/pages/index.tsx：首页组件，渲染 "Yay! Welcome to umi!" 欢迎页与示例图片；
• src/pages/docs.tsx：文档页示例；
• src/layouts/index.tsx：全局布局组件，使用umi提供的Link与Outlet组织导航栏（对应模板 index.tsx.tpl）；
• src/layouts/index.less：布局样式；
• src/assets/yay.jpg：欢迎页配图资源；
• package.json：由模板 package.json.tpl 渲染生成，默认提供dev、build、setup、start等脚本，依赖仅有umi，开发依赖为 React/ReactDOM 类型声明与 TypeScript；
• tsconfig.json、typings.d.ts：TypeScript 编译配置与全局类型声明。

生成后即可在项目根目录运行：

npm run dev

启动开发服务器；生产构建则使用：

npm run build

五、从源码看脚手架的工作原理

5.1 交互流程：向导如何一步步执行

核心生成器 packages/create-umi/src/index.ts 基于clackPrompts（Clack 交互组件）实现交互式向导，执行顺序为：

1. 输入项目名：默认值my-app，若同名文件夹已存在会提示 "Folder xxx already exists"；
2. 选择应用模板（详见 5.3）；
3. 选择 Npm 客户端；
4. 选择镜像源；
5. （仅插件模板）输入插件名，默认umi-plugin-demo；
6. 收尾输出 "You're all set!"。

任何一步按Ctrl+C取消，都会打印红色的 "Exit create-umi" 并以退出码 1 结束。

5.2 模板渲染：变量注入

选择完毕后，脚手架通过BaseGenerator将模板文件渲染到目标目录（injectInternalTemplateFiles），注入的模板变量包括：

{ version: version.includes('-canary.') ? version : `^${version}`, // 依赖版本号 npmClient, // 所选包管理器 registry, // 所选镜像源 author, // 从 Git 全局配置读取的作者名 <邮箱> email, // Git 邮箱 withHusky, // 是否安装 Husky（monorepo 内不启用） extraNpmrc, // pnpm v7 需要追加的 .npmrc 配置 pluginName, // 插件名（插件模板专用） }

注意author/email并非手动输入，而是通过getGitInfo()自动读取本机 Git 全局配置，没有配置时留空。版本号若包含-canary.前缀（预发版）则原样输出，否则统一使用^前缀以便获取同版本段的更新。

5.3 不止一种模板：四种内置模板

pnpm create umi并非只能生成基础 React 项目，向导第二步还会让你选择应用模板（selectAppTemplate），仓库内置四种模板（packages/create-umi/templates）：

5.4 外部模板：从 npm 拉取远程模板

除内置模板外，脚手架还支持通过--template参数指定 npm 上的远程模板，例如@umijs/electron-template。其实现位于 packages/create-umi/src/template.ts：脚手架会先请求${registry}${name}/latest获取最新版本号，再拼接出.tgz包地址并下载解压到目标目录（strip: 1去掉顶层目录）。模板名不完整时会自动补全，例如输入electron会依次尝试@umijs/electron-template等名称，下载失败会清理已创建目录并报错。

5.5 依赖安装与工程化细节

生成文件之后，脚手架还会做几件收尾工作（packages/create-umi/src/index.ts）：

• monorepo 检测：通过向上查找lerna.json或pnpm-workspace.yaml（detectMonorepoRoot）判断当前是否处于 monorepo 仓库内。若在 monorepo 内，生成的.npmrc会被移动到仓库根目录，且不初始化 Husky；
• Git 初始化：默认执行git init（可用--no-git跳过），已存在.git目录时直接跳过；
• 依赖安装：默认根据所选客户端与镜像源安装依赖，可用--no-install跳过；跳过且使用 pnpm v8 时，会提示建议运行pnpm up -L安装最新版本依赖；
• 测试保障：仓库的单元测试（packages/create-umi/src/index.test.ts）覆盖了app、plugin、max三种模板的生成与文件落盘验证，确保脚手架各路径稳定可用。

六、常用命令行参数速查

基于 CLI 解析逻辑（packages/create-umi/src/cli.ts）与参数定义（index.ts 的 IArgs），pnpm create umi支持以下常用参数：

七、小结

至此，一条pnpm create umi命令背后的完整链路已经清晰：向导收集项目名、模板、包管理器与镜像源 → 模板变量注入并渲染内置模板 → 检测 monorepo 与 Git 环境 → 按所选客户端安装依赖。无论你是想快速搭建一个可运行的基础 Umi 应用（Simple App）、一个 Vue 应用（Vue Simple App）、一个集成度更高的 Umi Max 工程（Ant Design Pro），还是一个插件开发骨架（Umi Plugin），脚手架都能一键完成，并把工程规范（tsconfig、typings、npm 脚本）一并配置到位。开发者可在此基础上直接进入业务开发，或参照 getting-started 指南 继续了解 Umi 的更多能力。

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