Ignite 生成器模板完全指南：从 ignite 目录到自定义脚手架-港品优选

Ignite 生成器模板完全指南：从 ignite 目录到自定义脚手架

【免费下载链接】igniteInfinite Red's battle-tested React Native project boilerplate, along with a CLI, component/model generators, and more! 9 years of continuous development and counting.项目地址: https://gitcode.com/GitHub_Trending/ig/ignite

ignite目录是 Infinite Red 的 Ignite 项目样板（boilerplate）中存放生成器模板的核心位置。本文围绕 docs/boilerplate/ignite.md 展开，系统讲解该目录的组织方式、内置的五大生成器（组件、屏幕、导航器、App 图标、启动屏）的用法与配置参数，并结合仓库源码（src/tools/generators.ts、src/commands/generate.ts）揭示生成器底层的 EJS 渲染、Front Matter 解析与图片变换原理。读完本文，你将能熟练使用 Ignite CLI 快速搭建应用骨架，并学会定制或从零创建属于自己的生成器模板。

一、ignite 目录是什么

在通过 Ignite CLI 创建的新应用里，会有一个ignite目录，其中包含一组初始生成器模板（generator templates），用于帮助你快速搭建新的屏幕（screen）、组件（component）、上下文（context）、App 图标（app icon）等。

在本文档所属的仓库中，这些模板的源头位于 boilerplate/ignite/templates/，包含四个子目录：

component/—— 组件模板（NAME.tsx.ejs）
navigator/—— 导航器模板（NAMENavigator.tsx.ejs）
screen/—— 屏幕模板（NAMEScreen.tsx.ejs）
app-icon/—— App 图标模板（android-adaptive-background.png、android-adaptive-foreground.png、android-legacy.png、ios-universal.png）
splash-screen/—— 启动屏模板（logo.png）

需要说明的是：当你npx ignite-cli new一个新项目时，CLI 会把这套模板复制到你的项目./ignite/templates/*目录下，之后生成器都从你项目内的这份模板读取内容。因此，修改自己项目里的模板即可改变后续所有生成结果。

生成器被官方称为"the true gem of Ignite"（Ignite 真正的宝石）：无论是做概念验证、Demo 还是生产应用，它都能帮你节省大量时间、保持代码风格一致、快速搭建基础结构。相关完整说明见 docs/concept/Generators.md 与 docs/concept/Generator-Templates.md。

二、生成器工作流：先认识命令入口

所有生成器都通过 Ignite CLI 的统一命令触发：

npx ignite-cli generate --list

（generate的简写别名是g，也支持generator/generators，见 src/commands/generate.ts）

--list会列出当前项目已安装的生成器清单。在源码中，showGeneratorHelp 还展示了--update、--dir、--case等选项的帮助信息，以及每个已安装生成器的推荐用法：

普通生成器：npx ignite-cli <generator> Demo
app-icon：npx ignite-cli app-icon all|ios|android|expo
splash-screen：npx ignite-cli splash-screen "#191015" [--android-size=180 --ios-size=212]

从 src/tools/generators.ts 的isIgniteProject可以看出，CLI 通过检查当前目录下是否存在ignite目录来判断是否处于 Ignite 项目根目录，所以请始终在项目根目录执行这些命令。

三、五大内置生成器详解

3.1 Component 生成器（使用最频繁）

这是你使用最多的生成器：

npx ignite-cli generate component MyAwesomeButton

它会基于 boilerplate/ignite/templates/component/NAME.tsx.ejs 生成一个新的组件函数。模板的 Front Matter 指定了输出目录：

--- destinationDir: app/components/<%= props.subdirectory %> ---

生成的组件自带项目约定的代码骨架：Props接口、useAppTheme()主题 Hook、ThemedStyle样式的$container/$text常量，与 app/components 下其他组件保持一致的书写风格。

3.2 Screen 生成器

生成一个"启用 Hooks"的屏幕：

npx ignite-cli generate screen Settings

屏幕模板 boilerplate/ignite/templates/screen/NAMEScreen.tsx.ejs 值得一提，它的 Front Matter 中不仅指定了destinationDir: app/screens，还带有一个patches配置，自动把新屏幕注册到导航类型里：

--- destinationDir: app/screens patches: - path: "app/navigators/navigationTypes.ts" replace: "// IGNITE_GENERATOR_ANCHOR_APP_STACK_PARAM_LIST" insert: "<%= props.pascalCaseName %>: undefined\n // IGNITE_GENERATOR_ANCHOR_APP_STACK_PARAM_LIST" ---

生成器会定位 app/navigators/navigationTypes.ts 中的锚点注释// IGNITE_GENERATOR_ANCHOR_APP_STACK_PARAM_LIST，在其上方插入新的路由参数类型，同时保留锚点以便下次继续插入。这就是"生成器同时更新关联文件"的典型例子，也是 Ignite 让脚手架"一次生成、处处连通"的关键设计。

3.3 Navigator 生成器

创建一个基于 React Navigation 的导航器到app/navigators目录：

npx ignite-cli generate navigator OrderPizza

模板 boilerplate/ignite/templates/navigator/NAMENavigator.tsx.ejs 会生成一个createNativeStackNavigator导航器，包含NavigatorParamList类型定义和默认的Demo屏幕。导航器的深入用法参见 docs/boilerplate/app/navigators/Navigation.md。

3.4 App Icon 生成器（特殊类型）

App 图标很棘手——尺寸形状繁多、配置文件与存放位置各异。为此 Ignite 提供了一个特殊生成器：它不仅渲染模板，还会直接修改原生工程目录，把输入图片缩放、变换后输出到对应位置。同时，它的第二个参数只接受预定义选项之一：ios、android、expo或all。

npx ignite-cli generate app-icon ios

模板文件夹ignite/templates/app-icon（源头见 boilerplate/ignite/templates/app-icon/）包含四个可自定义的输入文件：

模板文件	用途
`android-adaptive-background.png`	用于生成 Android 8.0+ 所需的全部自适应启动图标背景层；更新目录与旧版图标一致
`android-adaptive-foreground.png`	用于生成 Android 8.0+ 所需的全部自适应启动图标前景层；更新目录与旧版图标一致
`android-legacy.png`	用于生成 Android 7.1 及以下的全部旧版启动图标；会自动添加必要的内边距与圆角——自定义输入文件时不要自带内边距或圆角。（vanilla）更新`./android/app/src/main/res/`，包含`mipmap-anydpi-v26/ic_launcher.xml`；（expo）更新`./assets/images/`与根文件`./app.json`
`ios-universal.png`	用于生成 iOS 所需的全部 App 图标。（vanilla）更新`./ios/**/Images.xcassets/AppIcon.appiconset/`含`Content.json`；（expo）更新`./assets/images/`与根文件`./app.json`

更新模板文件时请注意：文件名必须保持不变，尺寸必须是 1024x1024px。

从源码 src/tools/generators.ts 的APP_ICON_RULESET可以看到底层生成逻辑的细节，例如旧版 Android 图标会使用sharp库做二次变换：

ic_launcher.png：先缩放至 812x812、圆角 64、四边内边距 106；
ic_launcher_round.png：缩放至 944x944、圆角 472、内边距 40；

随后按照各 DPI（mdpi 48 / hdpi 72 / xhdpi 96 / xxhdpi 144 / xxxhdpi 192）分别输出。iOS 侧则覆盖 iphone / ipad / ios-marketing 三种 idiom 下的多尺寸与倍率组合。

源码级安全校验：默认情况下，如果模板文件夹中的输入文件与 Ignite 自带图标的 MD5 签名一致，生成器会直接退出——这是为了鼓励你先把图标改成自己的内容。校验逻辑见 validateAppIconGenerator，它会依次检查：文件是否存在、尺寸是否为 1024x1024、MD5 是否与默认模板相同。

如果你确实想用 Ignite 自带的图标覆盖应用图标，可以分两步：先执行npx ignite-cli g app-icon --update重置模板文件夹，再用--skip-source-equality-validation标志重新生成。

3.5 Splash Screen 生成器

启动屏同样因平台和系统版本差异而难以手工配置，因此 Ignite 样板默认预配置好启动屏，并附带生成器方便定制。

与 App 图标生成器不同，启动屏生成器只需一个输入文件logo.png，位于ignite/templates/splash-screen（源头见 boilerplate/ignite/templates/splash-screen/logo.png）。生成器要求一个必填参数：启动屏背景色（十六进制格式）。

npx ignite-cli generate splash-screen FF0000 # 或 npx ignite-cli generate splash-screen "#FF0000" # 或 npx ignite-cli generate splash-screen fff

从 src/commands/generate/splash-screen.ts 可以看出：背景色缺省时会提示用法并退出；传入的色值若不以#开头会被自动补上；同时支持--android-size与--ios-size两个可选参数，默认值分别是androidSize = 180与iosSize = 212。

生成器会修改./assets/images/并尝试更新./app.json。但如果项目使用app.config.js或app.config.ts（Expo 动态配置），配置变更会输出到控制台，需要你手动同步（源码在检测到app.json缺失且存在app.config.*文件时触发该提示，见 src/tools/generators.ts）。

Logo 尺寸变换按平台预置，默认值在多数场景可用，但你可以用标志自定义：

npx ignite-cli generate splash-screen FF0000 --ios-size=150 --android-size=180

关于尺寸的注意事项：

iOS 无上限，取值需谨慎；
Android 上限为 288（源码校验androidSize >= 288会报错，见 validateSplashScreenGenerator），同时要求是大于 0 的数值；
Expo（Android 与 iOS）会遵循自定义尺寸，但由于 Expo 配置的要求，启动屏资源会带有内边距并尽量铺满屏幕。

源码中 Expo 侧实际生成多套资源（generateSplashScreen）：splash-logo-ios-mobile.png（1284x2778@3x）、splash-logo-ios-tablet.png（2048x2732@2x）、splash-logo-android-universal.png（1440x2560@4x）、Web 端 1920x1080，以及一张 1242x2436 的通用图，随后将splash/android.splash/ios.splash/web.splash配置合并写入app.json。

与 App 图标生成器相同，若输入文件未经修改（源码比对 MD5），启动屏生成器也会退出，鼓励你先完成自定义。

四、CLI 选项：--case 与 --dir

4.1 --case：控制生成文件名的大小写格式

默认情况下，生成文件的文件名采用PascalCase（--case auto或--case pascal）。--case开关用于指定模板文件名中NAME占位符被替换成何种格式。

例如npx ignite-cli@latest g screen log-in，按不同模板名会得到如下输出：

--case	模板文件名	生成的文件名
auto, pascal	NAMEScreen.tsx.ejs	LogInScreen.tsx
camel	NAMEScreen.tsx.ejs	logInScreen.tsx
snake	NAMEScreen.tsx.ejs	log_in_screen.tsx
kebab	NAMEScreen.tsx.ejs	log-in-screen.tsx
none	NAMEScreen.tsx.ejs	log-in.tsx
auto, pascal	NAME.tsx.ejs	LogIn.tsx
camel	NAME.tsx.ejs	logIn.tsx
snake	NAME.tsx.ejs	log_in.tsx
kebab	NAME.tsx.ejs	log-in.tsx
none	NAME.tsx.ejs	log-in.tsx

注意--case none时NAMEScreen.tsx.ejs生成log-in.tsx：此时NAME被替换为log-in，后缀Screen不再自动拼接。对应逻辑在 src/tools/generators.ts 的formattedName计算中实现，名称的pascalCase/kebabCase/camelCase/snakeCase四种变形由 src/commands/generate.ts 预先计算。

4.2 --dir：覆盖输出路径

--dir指定生成文件的输出路径，优先级高于模板默认路径（当前为app/）以及 Front Matter 中的destinationDir：

npx ignite-cli g model Episodes --dir src/context

这一选项对于使用文件路由的导航体系（如 Expo Router）特别有用。从源码 src/tools/generators.ts 可以看到优先级顺序：options.dir（CLI 传入）> Front Matter 的destinationDir> 默认的app/<generator复数>/。此外，在 src/commands/generate.ts 中，当检测到项目使用expo-router时，route生成器还会交互式询问目标目录（默认给出src/app或app），并支持自动创建不存在的目录。

4.3 其他实用行为

子目录支持：名称中带/时，会把/之前的部分解析为子目录并传入props.subdirectory（见 src/commands/generate.ts），组件模板的destinationDir: app/components/<%= props.subdirectory %>正是消费该值；
自动去重后缀：如果传入的名称以生成器名结尾（如MyButtonComponent），CLI 会自动剥离Component后缀并提示你无需手动添加（见 src/commands/generate.ts）；
--overwrite：目标文件已存在时默认跳过，加--overwrite才会覆盖（见 src/commands/generate.ts）。

五、模板语法：EJS 与 Props

模板使用 EJS 编写——一种基于 JavaScript 的模板语言。你可以随意书写模板，用<%= foo %>执行并输出 JS 表达式，用<% if (condition) { %>...<% } %>做条件控制。

生成器向模板注入一个props对象，包含以下属性：

props.filename // string，正在生成的文件名（如 "UserModel.tsx"） props.pascalCaseName // string，传入名称的 PascalCase 版本（如 "UserModel"） props.camelCaseName // string，camelCase 版本（如 "userModel"） props.kebabCaseName // string，kebab-case 版本（如 "user-model"） props.subdirectory // string，目标文件所在子目录路径（如 "my/sub/path/"）

（源码 generateFromTemplate 中还会额外注入snakeCaseName，并把name、originalName、overwrite等选项一并并入props。）

在模板中使用示例：

type <%= props.pascalCaseName %>Props = { some: string } export function <%= props.pascalCaseName %>(props: <%= props.pascalCaseName %>Props) { return <Text>{props.some} in a <%= props.pascalCaseName %> component!</Text> }

5.1 目录与文件命名约定

模板放在./ignite/templates目录下，文件夹名需与生成器名一致。例如想运行npx ignite-cli generate header Pizza，就把模板放在./ignite/templates/header/文件夹；该文件夹内所有文件都会被复制并按传入的名称渲染。
模板文件名中全大写的NAME会被替换为传入名称的 PascalCase 版本。例如NAMEScreen.ts在npx ignite-cli generate screen Pizza时生成PizzaScreen.ts。
如果想自定义文件名，可在模板 Front Matter 中提供filename：

--- filename: <%= props.camelCaseName %>.tsx ---

六、Front Matter：模板的元数据配置

"Front Matter" 是写在模板最开头的元数据块，用上下各三个横线（---）分隔，生成时会被剥离、不会出现在产物文件中。解析逻辑在 src/tools/generators.ts，它按---切分内容，前半部分按 YAML 解析成数据，后半部分才是真正渲染进文件的模板正文。

支持以下 Front Matter 选项：

6.1 destinationDir

定制模板的输出目标目录。例如在./ignite/templates/navigator/*中：

--- destinationDir: app/navigation --- import { StackNavigator } from "react-navigation" // ...

这样文件会输出到./app/navigation/*，而不是默认的./app/navigators/*。

6.2 patch / patches

允许对另一个文件打补丁（例如导出索引文件）。单个patch的示例：

--- patch: path: "app/screens/index.ts" append: "export * from \"./<%= props.kebabCaseName %>/<%= props.kebabCaseName %>-screen\"\n" ---

也可以使用数组形式的patches（屏幕模板即用此形式，见上文 3.2 节）。源码 handlePatches 支持三种动作：

append：向目标文件末尾追加内容；
prepend：在目标文件开头插入内容；
replace+insert：把目标文件中replace指定的文本替换为insert的内容（屏幕模板的锚点插入正是这种用法）。

补丁只在目标文件尚不存在时执行（见 src/tools/generators.ts），避免重复插入。

七、自定义与自建生成器

完全可以把提供的模板改成自己的：直接修改./ignite/templates/*下的文件，之后所有生成结果都会使用你更新后的文件。

自建生成器同样简单：你的生成器就存放在应用的./ignite/templates/*里。新建生成器时，参考项目里已有的模板——它们都是*.ejs文件（生成时会被 EJS 解释）。新建一个文件夹（如./ignite/templates/header/）并放入模板文件，运行npx ignite-cli generate header Pizza即可立即生效，无需任何额外注册。详细指引见 docs/concept/Generator-Templates.md。

八、更新生成器

想把自己的生成器更新到 Ignite 最新版本时，在项目根目录运行：

npx ignite-cli update <type> # 或更新全部 npx ignite-cli update --all

这会从 Ignite 把最新的生成器复制覆盖到你的项目。--update也可以直接附加在生成命令后（如npx ignite-cli g model --update，源码 updateGenerators 支持按名称更新单个或全部）。

⚠️注意：这会清除你所有的自定义修改，请务必先提交一次 commit，以便随时回滚！

另外，CLI 的--list帮助信息（showGeneratorHelp）也提示：若某个生成器未安装但 Ignite 自带，会提示你先npx ignite-cli generate <generator> --update再重试——即--update也可用于补齐缺失的生成器。

九、Windows 用户的注意事项

如果在 Windows 上生成源文件（如 screen 或 model）时发现新文件里 Front Matter 没有被剥离，很可能是换行符（End of Line）配置不当导致的。Ignite 会尽力自行处理，但有时你的机器缺少unix2dos之类的命令行工具（该工具通常随 Git 一起安装）。

此时可以打开 VS Code（或其他 IDE），把ignite/templates目录下所有ejs文件的换行符统一转换（如统一为 LF 或 CRLF），然后重新运行生成命令，新文件就会正常生成。

十、源码级原理速览

最后，从实现层面总结生成器的完整链路，便于你深入阅读 src/tools/generators.ts：

命令入口：npx ignite-cli generate <type> <name>进入 src/commands/generate.ts，解析生成器类型、名称、子目录、--dir、--case、--overwrite等参数；
模板发现：installedGenerators()扫描项目ignite/templates下的子目录，得到可用生成器列表；
EJS 渲染：generateFromTemplate()读取每个*.ejs文件，计算名称的四种大小写变形，渲染 EJS 并把props注入模板；
Front Matter 解析：按---切分，解析destinationDir/filename/patch/patches，确定目标路径并执行文件补丁；
写入产物：目标不存在则创建，存在则按overwrite决定覆盖或跳过，最终打印 "Generated new files" 清单；
特殊生成器：app-icon与splash-screen走 src/commands/generate/app-icon.ts 与 src/commands/generate/splash-screen.ts，用sharp做图片缩放/圆角/内边距变换，并按平台写入原生资源目录或 Expo 的assets/images与app.json。

围绕生成器的 CLI 总览（含new、cache、doctor、rename、remove-demo等命令）可继续阅读 docs/cli/Ignite-CLI.md；模板机制的完整阐述见 docs/concept/Generators.md 与 docs/concept/Generator-Templates.md。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析