Ignite CLI 完全指南：React Native 项目从脚手架到日常维护的命令行工具箱

Ignite CLI 完全指南：React Native 项目从脚手架到日常维护的命令行工具箱

【免费下载链接】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 CLI 是 Infinite Red 出品的 React Native 项目脚手架工具，它不仅能通过一条命令生成一套"久经战场考验"（battle-tested）的完整项目，还内置了组件生成器、环境诊断、项目重命名、演示代码清理等一整套开发期工具。本文以 docs/cli/Ignite-CLI.md 为骨架，结合本仓库src/commands/下的真实实现源码，逐条讲解cache、doctor、generate、help、new、issue、remove-demo、rename、update等全部命令的用法、参数、别名与底层原理，读完你即可把 Ignite CLI 当作日常开发流水线的一部分熟练使用。

Ignite CLI 是什么

Ignite 是"Infinite Red 构建 React Native 应用最偏爱的方式"，它由三部分组成：一个 CLI、一份可复用的 React Native 项目样板（boilerplate），以及若干命令行生成器。CLI 负责把样板工程"打印"成你的新项目，并在此后持续帮你保持代码一致、快速产出新代码。

CLI 本身基于 gluegun 构建，入口在 src/cli.ts：它使用build()创建名为ignite-cli的运行时，注册src/commands/目录下的所有命令，并将 src/commands/help.ts 设为默认命令——也就是说，在终端里只敲npx ignite-cli而不带任何子命令时，你会看到完整的命令帮助列表。

无需全局安装，直接通过npx调用即可：

npx ignite-cli@latest [command]

使用@latest可以确保始终运行最新版本（参见 docs/cli/Troubleshooting.md 的推荐做法）。下面按命令逐个展开。

new：创建新项目（核心命令）

new是 Ignite CLI 的心脏，它通过交互式提示引导你生成一个全新的 React Native 项目：

npx ignite-cli new PizzaApp

执行时所有未在命令行中提供的选项都会以交互式提问的方式向你确认。如果你希望跳过所有提问、直接采用默认值开工，可以加上--yes：

npx ignite-cli new PizzaApp --yes

new 的全部选项

从源码看 new 的默认值与执行流程

src/commands/new.ts 中，每个选项的默认行为都有明确注释与实现：

• bundle identifier：默认值为com.${pascalCase(项目名).toLowerCase()}（src/commands/new.ts），未提供时会交互式询问；
• git：默认true，项目创建完成后会执行git init、git add -A并提交一条形如New Ignite <版本> app的初始提交；
• installDeps：默认true，安装依赖后还会额外运行npx expo install --fix以保证与当前 Expo SDK 的兼容性（CI 环境下跳过，因为该命令可能返回非零退出码）；
• workflow：默认cng（Continuous Native Generation，即通过 Expo Prebuild 按需生成原生目录）；选择manual时则会提交android/与ios/目录，并从.gitignore中移除对应条目；
• 超时保护：整个创建流程设有 10 分钟（MAX_APP_CREATION_TIME = 10 * 60 * 1000）的硬超时，超时即退出并提示可用--debug复跑排查（src/commands/new.ts）；
• useCache：源码注释与文档一致，当前默认值为false（const defaultUseCache = false），意味着默认走全新安装路径，但若缓存命中且显式开启--useCache，会直接把缓存的node_modules与锁文件拷贝进项目，大幅缩短安装时间。

包管理器选择

new支持npm、yarn、pnpm、bun四种包管理器。CLI 会先探测系统上可用的包管理器：如果未显式指定，默认优先推荐pnpm（不可用时回退npm），并交互式询问。源码还会针对不同包管理器做适配：使用pnpm时在.npmrc追加node-linker=hoisted；使用 yarn v4+ 时修正.yarnrc.yml的nodeLinker: node-modules并创建空的yarn.lock（src/commands/new.ts）。

实验性特性：--experimental

--experimental接受逗号分隔的标记列表，目前支持：

• expo-router：将项目从 React Navigation 转换为使用 Expo Router（注意：会移除演示应用）；
• expo-canary：使用 Expo 高度实验性的 canary 发布版本，而非最新稳定 SDK；
• expo-beta：使用 Expo 最新的 beta SDK，而非最新稳定版本。

示例：

npx ignite-cli new PizzaApp --workflow=cng --experimental=expo-router npx ignite-cli new PizzaApp --workflow=cng --experimental=expo-router,expo-beta

从源码看，expo-router会强制把--removeDemo置为true以便于转换（src/commands/new.ts），并在创建后执行一连串改造：把app/目录迁移到src/、更新代码引用、改写 Reactotron 命令、为 screen 和 route 生成配套的 Expo Router 模板（src/commands/new.ts）。选择expo-router时还会在app.json中启用experiments.typedRoutes并注册expo-router插件。

generate：代码生成器（日常最高频命令）

npx ignite-cli generate

别名：npx ignite-cli g。

generate让你用自动化方式快速搭建新的组件（component）、页面（screen）、导航器（navigator）、应用图标（app-icon）、启动屏（splash-screen）等，从而保证代码风格一致并节省大量重复劳动。生成器模板位于新项目的./ignite/templates/*目录，生成逻辑实现在 src/commands/generate.ts。

常用示例：

npx ignite-cli generate component MyAwesomeButton # 生成组件 npx ignite-cli generate screen Settings # 生成 hooks 风格的页面 npx ignite-cli generate navigator OrderPizza # 在 app/navigators 下生成导航器 npx ignite-cli generate --list # 列出当前可用的生成器

几个实用细节（源自 docs/concept/Generators.md）：

• 命名去重：命令会自动剥离名称末尾与生成器同名的后缀，比如npx ignite-cli generate component MyButtonComponent会被处理为MyButton，避免出现MyButtonComponentComponent这类命名（src/commands/generate.ts）；
• 子目录支持：名称中带/时（如g component auth/Login）会解析出子目录层级；
• --overwrite：目标文件已存在时会跳过，加--overwrite可强制覆盖（src/commands/generate.ts）。

--case：控制生成文件名的命名风格

默认情况下文件名采用 PascalCase（--case auto或--case pascal）。例如：

npx ignite-cli@latest g screen Episodes # 生成 EpisodesScreen.tsx

--case开关决定模板文件名中的NAME部分如何被转换。以npx ignite-cli@latest g screen log-in为例：

--dir：指定输出目录

--dir覆盖生成文件的输出路径，优先级高于模板 front matter 中的destinationDir和默认的app/目录。这对使用 Expo Router 这类基于文件路由的导航体系特别有用。在generate命令的源码中，--dir与第三个位置参数都会被读取，并且当检测到项目依赖expo-router时，会智能地在src/app（或app）目录中询问放置位置（src/commands/generate.ts）。

特化生成器：app-icon 与 splash-screen

• app-icon：只接受ios、android、expo、all四种目标参数。它会把ignite/templates/app-icon下的android-adaptive-background.png、android-adaptive-foreground.png、android-legacy.png、ios-universal.png等输入文件缩放并转换后写入各平台的原生图标目录（vanilla 工作流写入android/app/src/main/res/与 iOS 的Images.xcassets；expo 工作流写入assets/images/并更新app.json）。输入文件需保持 1024x1024px 尺寸；
• splash-screen：只接收一个十六进制背景色参数：

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

可使用--ios-size、--android-size调整 logo 缩放尺寸（Android 上限为 288，iOS 无上限），例如：

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

两个生成器都带有"源文件一致性校验"：若模板中的输入文件与 Ignite 默认图标签名一致，命令会退出并提示你先做自定义；如需强制覆盖，可用npx ignite-cli g app-icon --update重置模板，再配合--skip-source-equality-validation重新生成。

关于自定义与创建生成器的完整内容，参见 docs/concept/Generators.md。

cache：依赖缓存管理

npx ignite-cli cache

别名：npx ignite-cli c。

new命令的--useCache标记允许把安装好的依赖缓存起来，以加速后续的new。cache命令专门用于与该依赖缓存目录交互（默认该标记为false）。

子命令

• npx ignite-cli cache help：输出 cache 子命令的帮助信息；
• npx ignite-cli cache path：输出本机缓存目录的路径；
• npx ignite-cli cache clear：删除本机缓存目录。

子命令分发逻辑在 src/commands/cache.ts，而缓存目录的底层实现在 src/tools/cache.ts：缓存根目录按平台区分——macOS 为~/Library/Caches/ignite，Windows 为AppData/Local/Temp/ignite，Linux 为~/.cache/ignite；缓存 key 是 boilerplate 的package.json内容的 MD5 哈希，每个缓存条目内保存对应包管理器的node_modules目录与锁文件（yarn.lock/pnpm-lock.yaml/package-lock.json/bun.lockb）。

doctor：环境体检报告

npx ignite-cli doctor

doctor检查你的开发环境依赖并提供版本信息，在向 Ignite 反馈问题时尤其有用。其实现位于 src/commands/doctor.ts，它会依次探测系统、JavaScript 运行时与全局包、Ignite 自身、Android（Java/ANDROID_HOME）、iOS（仅 macOS 下检查 Xcode 与 CocoaPods）、以及 git 工具链，并以表格形式输出。

下面是一份典型的输出示例（来自 docs/cli/Ignite-CLI.md）：

System platform darwin arch arm64 cpu 10 cores Apple M1 Pro directory ExpoPlist /Users/irignite/code/ExpoPlist JavaScript (and globally-installed packages) node 16.14.2 /Users/irignite/.nvm/versions/node/v16.14.2/bin/node npm 8.5.0 /Users/irignite/.nvm/versions/node/v16.14.2/bin/npm corepack 0.10.0 eas-cli 2.5.1 expo-cli 6.0.6 gatsby-cli 4.21.0 ignite-cli 8.3.0 npm 8.5.0 vercel 28.4.12 yarn 1.22.19 yarn 1.22.19 /Users/irignite/.nvm/versions/node/v16.14.2/bin/yarn create-expo-app 1.1.2 pnpm - not installed expo 46.0.16 managed Ignite ignite-cli 8.3.0 /Users/irignite/.nvm/versions/node/v16.14.2/bin/ignite ignite src src /Users/irignite/code/ignite/src Android java 11.0.14.1 /Users/irignite/.asdf/shims/java android home - /Users/irignite/Library/Android/sdk iOS xcode 14.0.1 cocoapods 1.11.3 /opt/homebrew/bin/pod Tools git git version 2.37.0 (Apple Git-136) /usr/bin/git

注意：实际输出的具体版本号取决于你机器上的安装情况，上述内容仅是展示输出结构的样例。doctor的输出同时也是下面issue命令采集问题上下文的数据来源。

issue：一键提交带环境信息的问题

npx ignite-cli issue "Mac M1 install trouble"

别名：npx ignite-cli i。

issue命令会在浏览器中打开一个针对 Ignite 的新问题表单，并自动用标题参数和采集到的doctor输出预填内容。你只需补充可复现问题的步骤（以及相关代码片段或仓库地址）即可提交。

源码逻辑（src/commands/issue.ts）清楚地展示了它的工作流：

1. 校验标题参数，未提供时给出提示；若标题未加引号且包含多个词，会询问是否合并成完整标题（src/commands/issue.ts）；
2. 后台运行ignite doctor采集系统与项目详情，并通过 src/tools/strip-ansi.ts 剥离终端着色控制字符（src/commands/issue.ts）；
3. 将标题与doctor输出拼装成问题正文，用系统默认浏览器打开预填好的新问题页面（macOS 用open，其他平台用start）。

因此issue可以看作是doctor的"接力"命令：先诊断、再上报，让维护者拿到完整的环境上下文。

rename：项目重命名

npx ignite-cli rename

别名：npx ignite-cli rn。

rename将当前项目重命名为你想要的新名称，同时也会帮你切换 bundle identifier。它要求你在项目根目录（存在app.json）下运行，旧名称与旧 bundle identifier 均从app.json读取（src/commands/rename.ts）。若未提供新名称或新 bundle，会交互式询问：

npx ignite-cli rename NewName com.mycompany.newname

源码在重命名完成后会明确提示几个注意事项：rename 功能并非在所有场景下都 100% 完美，建议提交前仔细检查git diff；同时需要重新运行pod install并重建应用与缓存（src/commands/rename.ts）。

remove-demo 与 remove-demo-markup：清理演示代码

npx ignite-cli remove-demo

别名：npx ignite-cli rd、npx ignite-cli remove-demos。

从生成的样板中移除全部演示代码（文件、被标记的代码块与代码行）。其实现见 src/commands/remove-demo.ts，它通过识别样板中以DEMO_MARKUP_PREFIX标记的注释块来定位需要删除的代码段，并递归查找并删除demo目录与清理产生的空目录。

与它互补的是只清理注释标记的命令：

npx ignite-cli remove-demo-markup

别名：npx ignite-cli rdm。

remove-demo-markup只移除样板中的演示标记注释（comments only），不删除任何实际代码，实现在 src/commands/remove-demo-markup.ts。

--dry-run：先预览再执行

两个命令都支持--dry-run：

npx ignite-cli remove-demo --dry-run # 列出会被修改/删除的文件，但不真正执行 npx ignite-cli remove-demo-markup --dry-run # 显示会被移除的标记内容，但不真正执行

这是一个非常实用的安全特性：在正式清理前先预览影响范围，确认无误后再实际执行。

update：更新生成器模板

npx ignite-cli update

update用于更新项目中现有的生成器模板，可用来把旧版本 Ignite 生成的项目中的模板升级到最新版本。不带参数时它会展示生成器帮助；在项目根目录执行以下命令即可：

npx ignite-cli update <type> # 更新指定类型的模板 npx ignite-cli update --all # 更新全部模板

实现位于 src/commands/update.ts：传入--all或具体类型时调用updateGenerators从 Ignite 拷贝最新模板到项目。⚠️ 注意：该操作会覆盖你对模板的所有自定义，务必先提交一次 git commit以便回滚（参见 docs/concept/Generators.md 中的说明）。

help：随时可查的命令手册

npx ignite-cli help

别名：npx ignite-cli h。

help在终端中列出全部命令及每条命令的简要说明（src/commands/help.ts）。它是cli.ts中注册的默认命令，所以直接执行npx ignite-cli也会得到同样效果。此外，npx ignite-cli help generate（或help g）会进一步展示生成器的专属帮助。

使用建议与最佳实践

综合以上命令与源码，可以整理出几条直接可用的工作流：

1. 初始化项目：npx ignite-cli@latest new PizzaApp --yes快速拿到默认配置的可用项目；首次使用建议保留 demo 代码作为学习参考；
2. 加速重复创建：第一次安装依赖后，用npx ignite-cli cache path确认缓存位置，后续配合--useCache显著加快新项目创建；
3. 保持代码一致：用npx ignite-cli generate component/screen/navigator生成新代码，利用--case控制命名风格、--dir控制输出位置；
4. 上线前清理：用remove-demo --dry-run预览、再正式执行，把样板演示代码从生产项目里彻底移除；
5. 遇到问题先诊断：npx ignite-cli doctor检查环境，必要时用npx ignite-cli issue "问题描述"一键带上完整环境信息反馈；
6. 升级模板：在项目根目录用npx ignite-cli update --all（先提交 git）同步最新生成器。

如果创建或使用过程中遇到环境层面的问题，比如旧版本全局安装导致的版本冲突，可以参考 docs/cli/Troubleshooting.md：用npx ignite-cli@latest运行命令，并通过npm uninstall --global ignite-cli（或yarn global remove ignite-cli、pnpm remove ignite-cli -g）清除旧的全局安装。

小结

Ignite CLI 的九大命令覆盖了 React Native 应用从"出生"（new）到日常生长（generate、update）、再到交付与排障（remove-demo、doctor、issue）的全生命周期。本文逐一拆解了这些命令的参数与默认值，并对照 src/commands/ 下的源码说明了它们的底层行为，让你不仅能"会用"，还能理解每条命令背后究竟做了什么。更底层的生成器机制可进一步阅读 docs/concept/Generators.md 与 docs/Guide.md 中的相关章节。

【免费下载链接】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