create-react-admin-template

创建企业级 React 管理后台项目。PageForm、AppTable、枚举、API 生成工具等能力最终都是项目 本地源码，不作为内部运行时 npm 包引用。

创建项目

pnpm create react-admin-template@latest
# 在向导中填写名称，例如 my-admin
cd my-admin
pnpm dev

终端中会打开交互向导：选择精简版 core、完整版 full 或自定义 custom，自定义时 勾选所需能力，再选择是否立即安装依赖。先填写项目名称，名称输入框为空白且必填； 也可在命令末尾直接传入目录名，跳过名称输入。 上下键切换选项，空格勾选，回车确认；Ctrl+C 取消。安装时显示进度提示，结束后显示 进入目录及启动命令。创建时按目录设置包名、应用标题、品牌和存储命名空间；支持 --package-name @acme/admin --title "Acme 后台" 覆盖，中文目录需显式指定合法 npm 包名。 依赖安装使用锁文件并输出实际日志。安装失败保留完整源码，进入项目后重试 pnpm install --frozen-lockfile；明确取消创建才清理新目录。 项目化配置见生成项目中的 docs/guide/scaffold-guide.md。

显式传入档位、能力列表或 --yes 会跳过向导，适合脚本与 CI；非交互环境默认 core 并 安装依赖。显式指定档位或能力但未提供名称时，终端中只补问项目名称。 --yes 和非交互环境要求提供目录参数。--skip-install 跳过安装：

pnpm create react-admin-template@latest my-admin --profile full
pnpm create react-admin-template@latest my-admin --capabilities advancedTable,filePreview
pnpm create react-admin-template@latest my-admin --yes --skip-install

--capabilities 是在 core 基础上增加的能力，不填 --profile 时自动使用 custom。 --profile custom --capabilities "" 表示不增加可选能力；不能与 core/full 档位组合。 可选项由 tools/scaffold/capability-catalog.json 统一声明；增加能力时填写显示名称 strLabel、说明 strDescription、源码路径及依赖，无需修改向导。

交互界面使用 MIT 许可的 @clack/prompts，仅作为创建器依赖，不进入生成应用。 创建器使用 Prettier 格式化生成的 JSON，确保产物符合应用已有的格式检查规则。

也可以使用等价命令 pnpm dlx create-react-admin-template@latest。

添加能力

在已有项目中读取创建时的模板版本，使用同版本创建器追加源码：

strTemplateVersion=$(node -p "require('./.scaffold-state.json').strTemplateVersion")
pnpm dlx "create-react-admin-template@$strTemplateVersion" add --target . --capability filePreview

--skip-install 跳过依赖安装；新增依赖时仍由 pnpm 在临时目录准备锁文件，可能读取 Registry 元数据，不下载依赖或执行生命周期脚本。新增能力使用同版本模板锁定的版本，保留业务依赖。 版本不匹配、能力已存在或目标文件冲突会报错；锁文件准备失败不修改项目，安装失败 保留已添加内容并提示重试。无需克隆完整模板仓库，应用不依赖创建器运行时。

生成应用内的 pnpm scaffold:feature ... --with-page 提供列表、编辑表单、行为测试和 独立路由接线文件，默认预览；追加 --write 创建，主路由仍按预览显式注册。

维护与发布

当前两个自有内建组件已获项目所有者公开分发授权，依据记录在组件来源清单中。 prepublishOnly 仍检查授权并运行完整发布验收，未授权组件会阻止发布。 在源码仓库内进入本包目录同步版本并发布；本例版本仅供演示：

cd packages/create-react-admin-template
pnpm release:prepare --version 0.4.0
pnpm release:prepare --version 0.4.0 --write
npm login --registry=https://registry.npmjs.org --auth-type=web
npm publish

• prepack 按 tools/scaffold/distribution.mjs 从根应用生成本包的 template/。 仓库只复制已跟踪或未被 Git 忽略的新增文件；应用路径和创建器运行资产分别声明。
• prepublishOnly 先检查组件清单的公开分发授权，再调用统一的 release:verify，运行根仓库完整门禁和独立安装包测试；失败即停止发布。 普通 npm publish 不要求 Git 工作区已提交，版本一致性继续由 prepack 校验。
• release:prepare 默认只预览，--write 同步 CLI/模板版本和变更记录，不执行验证或发布。
• 根应用继续保持 private: true。模板快照不提交 Git，维护脚本不进入生成项目。
• 生成应用会移除共享配置中的维护段，使用项目开发 README；可选能力文档始终保留， 源码和测试按所选档位交付。初始化后的项目也必须能通过配置测试。
• 发布前确认 npm 登录有效、包名归属及许可证。npm 已存在的版本不能再次发布，需要准备 新版本；浏览器认证失败时重新运行上述登录命令，使用新生成的认证链接。

只验证或生成 tarball、不发布：

pnpm release:verify # 与 npm publish 使用相同验收
pnpm test:package  # 只检查安装包结构与生成流程
pnpm pack          # 只生成 tarball

维护时先在本目录运行 pnpm install --frozen-lockfile，安装 CLI 依赖。包自测会通过 npm 安装本地 tarball 及它声明的第三方依赖，需要 Registry 可访问（有缓存时可复用）；创建 快速测试项目时跳过应用安装；cold 测试为 core/full/custom 分别独立安装锁定依赖，启动 浏览器，生成页面并接线，初始化后运行完整门禁。也可在打包后执行 node bin/create.mjs 验证终端向导。CI 支持该流程，Chromium 先通过根 pnpm test:browser:install 安装。

cold 构建通过临时进程中的测试许可证占位值验证配置路径；这不验证商业授权，生成应用的 许可证配置仍由项目提供。许可证拒绝测试会独立设置空值，不受本地或 CI 的 Key 影响。

cold 的示例路由插入 config.ts 的 arrAuthenticatedRoutes，保留首页在首位； 维护接线时使用完整注册位置，不能只匹配同时出现在 import 中的路由变量名。

发布版本由本目录的 package.json#version 声明，必须与根目录 scaffold.template.json#strAppliedVersion 一致，否则 prepack 会报错。模板升级时同步 更新这两个版本及 docs/engineering/template-changelog.md；派生应用自己的版本不受影响。

本包作为新名称单独发布，不会改名、撤回或自动替换已发布的旧创建器。模板 ID 保持不变， 已生成项目不需要因为创建器改名而迁移。