企业官网建设流程全解析

umi 自定义模板完全指南：从模板目录到团队共享

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

每次新成员入职，开工流程都差不多：拷贝团队标准工程、改项目名、删掉演示页面、装依赖，大部分时间耗在重复配置上。umi 的脚手架其实支持自定义模板：把团队的标准骨架打包成一个 npm 包，用一行umi create就能生成统一的新工程。本文讲清楚 umi 4 里模板是怎么被找到并处理的，以及搭出一个团队可用、可分享的模板的完整过程。

✅ 先看效果：一条命令生成标准化工程

最终成果是这样一个命令：

# 通过 --template 参数指定模板包名 pnpm create umi my-app --template my-team

执行后，当前目录下会得到一个 my-app 工程：依赖清单、目录结构、配置文件全部来自团队模板。不传--template时，命令会进入内置向导，从官方自带的 app、max、vue-app、plugin 四类骨架中选一个生成，官方说明见脚手架文档。

原理速览：umi 4 脚手架的模板下载与渲染机制

主流程在 packages/create-umi/src/index.ts，根据是否传了--template分成两条路：

• 内置模板：骨架放在packages/create-umi/templates/app/这类目录里，生成时由 BaseGenerator 渲染骨架中的.tpl文件（如 package.json.tpl），把版本号、包管理器、作者等变量从向导数据里填进去，随后初始化 git、安装依赖；
• 外部模板：只做“下载 + 解压”，不做变量替换。

下载规则在 packages/create-umi/src/template.ts：create-umi 把用户输入的名字按@umijs/<name>-template约定换算成包名，到 npm registry 查询最新版本，下载对应 tar 包并解压到目标目录（会剥掉一层顶层包目录）。所以“umi 自定义模板”本质上就是一个可发布的 npm 包，内容就是你要生成的工程骨架。

动手实践：搭一个团队可用的 umi 自定义模板

阶段一：整理模板包骨架

拿团队成熟工程做“模板化”处理：删掉业务页面和个人化配置，保留你想强制的规范（lint 规则、请求封装、布局、mock 约定），整理成一个 npm 包：

my-team-template/ ├── src/ # pages、layouts、components 等标准代码 ├── config/ # umi 配置（路由、代理、插件） ├── package.json # 依赖清单，即新工程的依赖清单 └── README.md # 给新成员的使用说明

注意两点：模板包的files字段决定 tar 包里有哪些内容；npm 压缩包默认带一层顶层目录，create-umi 解压时会剥掉这一层，所以骨架文件要放在包根目录，不要多套一层子目录。

阶段二：写“生成逻辑”并本地联调

外部模板没有变量替换，所谓生成逻辑主要是包元数据与少量个性化处理：

{ "name": "@umijs/my-team-template", "version": "1.0.0", "files": ["src", "config", "package.json", "README.md"] }

若新工程需要差异化取值（如项目名），在包里放一个 postinstall 脚本做占位替换，并在 README 里写清约定。本地联调分三步：

npm pack # 先验证 tar 包内容 # 发布到可访问的源后，在空目录里： pnpm create umi demo --template my-team

确认 demo 目录内容与预期骨架一致、依赖装完、工程能启动即可。

把模板发布给团队使用

包名必须符合@umijs/<name>-template形式，create-umi 只在这个范围内查找。团队若用私有源，就发布到私有源，成员在向导里选对应源即可。如果无法发包，退而求其次的共享方式是直接分享骨架仓库让成员 clone——git 模板支持在源码里还是 TODO 项。

🧩 umi 模板避坑清单：常见不生效原因

• 报错含not found from：包名少了-template后缀、不在 @umijs 范围，或版本没发到所选的源上
• 提示文件夹已存在：当前目录下有同名目录，删掉空目录或换个项目名
• 解压后文件位置不对：files字段漏配，tar 包必须是标准 npm 包结构
• pnpm v8 装出最小版本依赖：官方流程已提示执行pnpm up -L
• .tpl里的动态值没生效：外部模板不走 .tpl 渲染，这套机制只对内置模板有效
• 内网下载失败：在向导里切换到国内镜像源

⚡ 进阶玩法：交互式参数、条件渲染与模板继承

• 交互式参数收集：官方向导用 clack prompts 在终端依次询问项目名、包管理器、源，团队模板也可以在骨架根目录加一个 init 脚本，首跑时提问
• 条件渲染：内置模板靠.tpl后缀加数据对象（如 withHusky、pluginName）决定文件取舍，外部模板可在骨架里备好多份变体文件，用 postinstall 按需挑选
• 模板继承：从官方 packages/create-umi/templates/max/ 模板复制一份作底，删演示代码、加团队约定，只发布增量部分，维护成本明显更低

常见问题与行动建议

• 问：模板能直接指向一个 git 仓库吗？答：目前不行，git 模板支持仍是源码里的 TODO，现阶段走 npm 包流程。
• 问：模板升级后，已有工程会跟着更新吗？答：不会。create-umi 只参与“新建工程”这一步，老工程要统一改动，靠脚本或仓库里的 codemod 工具迁移。
• 问：新成员该用官方模板还是团队模板？答：建议默认团队模板；官方 app 是最小骨架，适合熟悉框架，max 模板面向中后台场景。

如果准备动手：挑一个团队成熟工程，删掉业务页面，按上文命名约定打包发布，把pnpm create umi <项目名> --template <模板名>这一行分享给团队，脚手架的搭建就完成了。

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