UmiJS 快速上手：从零创建项目与目录结构解析

一、开发环境准备与基准要求

在创建 UmiJS 项目之前，必须确保本地环境满足基础 Node.js 运行要求。Umi 4 深度整合了现代构建工具链，对运行时环境有明确的版本下限。

• Node.js 版本：要求 Node.js 16.14.0 或更高版本（推荐使用最新的 Node.js 18 LTS 或 20 LTS 版本，以获得更稳定的模块编译性能）。
• 包管理工具：支持 pnpm、yarn 或 npm。官方更推荐使用 pnpm，其基于硬链接的依赖存储机制能显著加快构建并规避幽灵依赖问题。
• 终端权限与路径：建议在纯英文路径的目录中操作，避免中文或特殊字符导致编译脚本路径解析异常。

可通过终端执行以下命令快速校验当前环境：

# 检查 Node.js 版本
node -v
# 示例输出：v18.19.0

# 检查 pnpm 是否安装（若未安装可执行 npm i -g pnpm）
pnpm -v
# 示例输出：8.15.0

二、从零创建并运行 Umi 项目

Umi 官方提供了 create-umi 脚手架工具，支持直接在空目录中以交互式问答的形式初始化工程模板。建议先手动创建一个项目文件夹并进入，然后在该目录内执行初始化指令。

1. 创建项目目录并触发脚手架

打开终端，执行以下命令序列：

# 1. 创建并进入专属项目目录
mkdir my-umi-app && cd my-umi-app

# 2. 运行官方脚手架（亦可使用 pnpm dlx create-umi@latest）
npx create-umi@latest

2. 交互选项配置

命令执行后，脚手架会依次弹出提示，请根据实际场景完成选择：

1. Select template to create (选择模板类型)： 终端会列出 Simple App（基础单页应用）与 Ant Design Pro（开箱即用的后台管理中台模板）等选项。初次学习建议选择 Simple App，其目录结构纯粹，利于掌握核心概念。
2. Pick Npm Client (选择包管理器)： 上下键移动光标选择 pnpm（若本地无 pnpm，可选择 npm 或 yarn）。
3. Pick Npm Registry (选择镜像源)： 在中国大陆网络环境下，建议选择 taobao（即 npmmirror 镜像），可明显提升依赖下载速度。

3. 安装依赖与启动本地服务

脚手架在生成基础文件后，若未自动安装依赖，需在当前项目根目录手动执行安装与启动命令：

# 安装依赖
pnpm install

# 启动本地开发服务
pnpm run dev

当终端输出类似 App listening at: http://localhost:8000 时，表明开发服务已就绪。在浏览器中访问 http://localhost:8000，即可看到 Umi 默认的欢迎页面。

三、核心目录与文件结构深度拆解

初始化完成后的项目结构体现了标准的约定式前端工程规范。理解每个目录的定位，能够帮助开发者快速组织业务逻辑与静态资源。一个典型的 Umi 4 根目录结构如下：

my-umi-app/
├── .umirc.ts            # 核心配置文件（编译时）
├── .gitignore           # Git 忽略提交规则
├── package.json         # 项目信息与脚本命令
├── tsconfig.json        # TypeScript 类型配置
├── mock/                # 本地模拟接口目录
│   └── api.ts
├── public/              # 静态资源原样直出目录
│   └── favicon.ico
└── src/                 # 业务源码主目录
    ├── .umi/            # 框架自动生成的临时运行时目录（严禁提交）
    ├── app.ts           # 运行时配置文件
    ├── layouts/         # 全局布局容器
    │   └── index.tsx
    ├── pages/           # 路由视图与页面组件
    │   ├── index.tsx
    │   ├── index.less
    │   └── docs.tsx
    ├── models/          # 全局或模块数据状态流
    └── services/        # 后端接口请求封装

1. 根级配置文件与开发支持目录

2. 核心业务目录 src/ 深度剖析

• src/pages/（页面组件）： 承载所有路由对应的 UI 界面。在默认的约定式路由下，Umi 会将该目录下的文件结构直接映射为 Web 路由地址。
• src/layouts/index.tsx（全局布局）： 外层布局组件。用于统筹页面公共骨架，如全局导航栏、侧边栏、面包屑或页脚，所有 pages 组件都会被包裹在 Layout 的 <Outlet /> 中进行渲染。
• src/app.ts(x)（运行时配置）： 与编译时的 .umirc.ts 不同，app.ts 运行在浏览器端。常用于注入网络请求拦截器、配置 initialState 全局初始化数据、或在路由切换时执行权限拦截逻辑。
• src/models/ 与 src/services/： 推荐的数据流分层规范。services 负责发送 Axios / Umi-Request 网络请求；models 负责使用数据流方案（如 useModel 简易状态或 Dva）沉淀数据并提供给各页面共享。

四、路由系统与运行时编译机制

UmiJS 核心机制之一是“约定优于配置”。开发者无需手动维护庞大繁琐的路由表，只需按照规范在 src/pages 中创建文件，编译内核便会自动推导并输出完整的单页应用路由。

1. 约定式路由的映射规则

常见的文件路径与实际访问 URL 对应关系如下：

• src/pages/index.tsx 映射为根路径 /。
• src/pages/users.tsx 或 src/pages/users/index.tsx 均映射为 /users。
• src/pages/users/[id].tsx 映射为动态参数路由 /users/:id。在组件内部可通过 useParams() 直接获取 id 参数。
• src/pages/404.tsx 会作为未匹配任何路径时的全局 404 兜底路由。

2. 约定式路由 vs 配置式路由

当企业级后台系统具有多级嵌套菜单、复杂的动态权限校验或面包屑配置需求时，亦可在 .umirc.ts 中开启配置式路由。只要配置文件中显式声明了 routes 数组，约定式路由将自动停用，完全以配置数组为准：

// .umirc.ts 中的配置式路由示例
import { defineConfig } from "umi";

export default defineConfig({
  routes: [
    { path: "/", component: "index" },
    { path: "/docs", component: "docs" },
    { path: "/users/:id", component: "users/[id]" },
    { path: "/*", component: "404" },
  ],
  npmClient: 'pnpm',
});

五、开发速查与避坑指南

为便于在实际日常开发中高效检索，下表与速查图整理了高频命令、配置选型考量以及开发者最常遇到的问题排查方案。

常见问题排查与解决

• 新增文件后页面报 404： 当使用部分特定编辑器（或只读文件监听受阻）时，约定式路由未能感知新增文件。此时停止终端服务，删除 src/.umi 缓存目录后重新执行 pnpm dev 即可解决。
• .umirc.ts 与 config/config.ts 共存冲突： Umi 规定二者只能二选一。若工程根目录下同时存在 .umirc.ts 与 config/config.ts，.umirc.ts 拥有更高优先级，会导致 config/ 下的修改全部失效。应删除根目录多余的 .umirc.ts。
• 动态路由参数读取失败： 动态路由文件名必须使用半角中括号包覆，如 [id].tsx 或 [userId]/profile.tsx，避免误写为冒号 :id.tsx。在组件内部需统一从 umi 包中引入 useParams 钩子函数获取参数。