create-keystone-app 版本演进解析：从 v10 到 v11 的脚手架变革与实现原理-开发者社区

后端

【免费下载链接】keystone

The superpowered headless CMS for Node.js — built with GraphQL and React

项目地址：https://gitcode.com/gh_mirrors/key/keystone

create-keystone-app是 Keystone 6 官方的项目脚手架 CLI：执行一条命令即可生成一套开箱即用的 Headless CMS 工程（含 GraphQL API 与 Admin UI 骨架）。本文以该包的 CHANGELOG.md 为骨架，逐版本解读 v10.0.0 到 v11.0.2 之间发生的行为变更（包管理器检测、移除自动安装、纯 ESM 化等），并结合 packages/create 下的实际源码与starter模板，讲清脚手架每次生成的完整流程与生成物的内部结构。读完你将掌握该 CLI 的当前用法、版本演进带来的迁移注意点，以及生成项目每个配置文件的作用与修改入口。

create-keystone-app 是什么

create-keystone-app是随 Keystone 6 一起维护的初始化工具，当前仓库内版本为11.0.2。它的作用是：交互式地询问目标目录，然后把 packages/create/starter 中的一份可运行 starter 工程复制到该目录，并给出安装依赖与启动的命令提示。

包的元信息定义在 packages/create/package.json：

bin指向./cli.js，即命令行可执行入口；
exports["."]指向构建产物dist/create-keystone-app.js；
preconstruct.entrypoints声明index.ts为唯一构建入口；
运行时依赖仅三个：enquirer（交互式提问）、meow（CLI 参数解析）、package-json（拉取 npm registry 元数据做版本自检）；
files字段说明发布包只包含dist、starter、cli.js。

而 packages/create/cli.js 本身只有两行——通过import 'create-keystone-app'引入包入口，真正的逻辑全部在 packages/create/src/index.ts。

一次脚手架生成的全流程（基于当前源码）

index.ts是理解整个 CLI 的最佳入口，它按顺序完成以下工作：

打印开场信息：使用 Node 内置util.styleText高亮 "Keystone 6" 字样；
版本自检（checkVersion）：通过package-json从 npm 拉取create-keystone-app的upstream版本，与本地package.json版本比较，不一致则在 stderr 提示“你正在运行旧版本，请更新到 x.y.z”（对应 packages/create/src/index.ts）；
参数归一化（normalizeArgs）：若命令行没有传入目录参数（cli.input[0]为空，cli由meow解析），则用enquirer交互式提问"What directory should create-keystone-app generate your app into?"，并对空输入做校验；最终用path.resolve将目录解析为绝对路径（packages/create/src/index.ts）；
创建目录并复制模板：fs.mkdir新建目标目录，然后并行复制 8 个 starter 文件（见下节）；
检测包管理器：从环境变量npm_config_user_agent推断当前使用的包管理器（见“包管理器检测”小节）；
输出后续指引：打印cd <目录>、<包管理器> install、<包管理器> run dev三步命令，并提示阅读生成目录下的README.md、编辑keystone.ts（packages/create/src/index.ts）。

入口处的meow定义了最简单的 CLI 用法，这也是本文档的核心命令形态：

Usage $ create-keystone-app [directory]

即支持create-keystone-app my-app直接指定目录，或不带参数进入交互式流程。

模板文件清单

复制逻辑位于 packages/create/src/index.ts，通过fs.copyFile将以下 8 个文件从starter复制到目标目录（_gitignore复制时重命名为.gitignore）：

starter 源文件	生成后的文件	作用
`_gitignore`	`.gitignore`	忽略 node_modules、.keystone、keystone.db 等产物
`schema.ts`	`schema.ts`	定义 User / Post / Tag 三个列表（list）
`package.json`	`package.json`	名为`keystone-app`的工程清单与 dev/build/start 脚本
`prisma.config.ts`	`prisma.config.ts`	Prisma CLI 的 schema 与 datasource 配置
`tsconfig.json`	`tsconfig.json`	TypeScript 编译配置
`keystone.ts`	`keystone.ts`	Keystone 配置入口（db、lists、session、apolloConfig）
`auth.ts`	`auth.ts`	基于`@keystone-6/auth`的登录与无状态会话配置
`README.md`	`README.md`	起步指引（数据库切换、鉴权说明、接入前端等）

全部文件均可直接在 packages/create/starter 目录中查看。

包管理器检测

生成结束后，CLI 需要提示用户用哪个包管理器安装依赖。v10.0.0 起引入了基于npm_config_user_agent的检测（这也是该版本在 CHANGELOG 中被标记为 Major Changes 的原因）：

const [packageManager] = process.env.npm_config_user_agent?.split('/', 1) ?? ['npm']

npm_config_user_agent形如npm/9.6.7 node/v20.0.0 linux x64，split('/', 1)只取第一个分隔段，即包管理器名（npm、pnpm、yarn等）。当用户通过 npm 启动 CLI 时，后续提示会输出npm install；若通过 pnpm 执行，则提示pnpm install——这正是“用你偏好的包管理器安装依赖”的设计落点。若环境变量缺失，则回退到npm。

starter 模板剖析：生成的工程长什么样

keystone.ts：Keystone 配置入口

packages/create/starter/keystone.ts 导出一个由withAuth包裹的config(...)对象，包含四块关键配置：

db：使用sqliteprovider，通过@prisma/adapter-better-sqlite3的PrismaBetterSqlite3适配器连接file:./keystone.db，追求最快的启动体验；onConnect钩子中，若User表为空，则用crypto.getRandomValues(new Uint8Array(16)).toHex()生成 16 字节随机密码，自动创建admin@example.com初始用户并打印到控制台（代码注释明确警告：该逻辑仅用于开发环境，不可用于生产）；
apolloConfig.plugins：注册 Apollo 插件，在每次 GraphQL 请求开始时打印 operationName，在遇到错误时打印错误堆栈，方便开发期观察 API 行为；
lists：从./schema.ts导入的列表定义；
session：从./auth.ts导入的会话策略。

schema.ts：User / Post / Tag 三列表

packages/create/starter/schema.ts 展示了几种最常用的字段类型与关系写法，同时用satisfies Lists约束类型（Lists来自生成目录下./generated/keystone/types）：

User：name（必填文本）、email（必填且isIndexed: 'unique'唯一索引）、password（密码字段）、posts（一对多关系ref: 'Post.author'）、createdAt（defaultValue: { kind: 'now' }自动记录创建时间）；
Post：title（必填文本）、content（来自@keystone-6/fields-document的文档字段，开启formatting、links、dividers及五种分栏布局）、author（卡片式 UI 的关系字段，many: false单作者）、tags（多对多关系ref: 'Tag.posts'，many: true）；
Tag：仅name与反向posts关系，并通过ui.hideNavigation在 Admin UI 导航中隐藏。

三个列表的access均设为allowAll，注释反复强调：这是 starter 的默认开放策略，生产环境务必参考访问控制指南收紧。

auth.ts：登录与会话

packages/create/starter/auth.ts 用createAuth配置基于 email + password 的认证（listKey: 'User'、identityField: 'email'、secretField: 'password'，sessionData片段为'name createdAt'），并用statelessSessions提供 cookie 无状态会话，maxAge为 30 天（60 * 60 * 24 * 30），密钥取自process.env.SESSION_SECRET。

其余配置文件

packages/create/starter/package.json：提供dev（keystone dev）、start（keystone start）、build（keystone build）三个脚本；
packages/create/starter/prisma.config.ts：供 Prisma CLI 使用，schema指向schema.prisma，datasource.url为file:./keystone.db——注意 Prisma CLI 与 Keystone 运行时分别从这里和keystone.ts的 adapter 读取连接，切换数据库时两处都要改；
packages/create/starter/tsconfig.json：target: esnext、module: commonjs、strict: true、noEmit: true。

CHANGELOG 逐版本解读：v10 到 v11 的三次大变化

以下所有条目均来自 packages/create/CHANGELOG.md 原文，按版本顺序解读其行为影响：

10.0.0 —— 包管理器检测

Adds support fornpm_config_user_agentfor determining your package manager

这是本包进入 10.x 的第一个破坏性变更：CLI 开始读取npm_config_user_agent来判断用户使用的包管理器，从而在“安装依赖”的后续指引中输出与之一致的命令。其源码实现即上文“包管理器检测”小节中的一行代码。

10.0.1 / 10.0.2 / 10.0.3 —— 模板与输出的修复

10.0.1：Update generated schemas，更新生成的 schema 文件（即 starter 内列表定义所对应的 GraphQL/Prisma schema 产出）；
10.0.2：Fix starter script error when looking for pre-built schemas，修复 starter 脚本在查找预构建 schema 时的报错；
10.0.3：Fix output formatting for CLI instructions，修复 CLI 指引文案的输出格式。

11.0.0 —— 三项重大变更

这是 CHANGELOG 中信息量最大的一个版本，包含三个 Major Changes：

移除自动安装依赖：Removes auto-install, use your preferred package manager to install dependencies instead。此前 CLI 可能自动安装依赖，现在不再自动安装，改由用户用自己偏好的包管理器执行（对应生成的指引命令npm install/pnpm install等）；
升级keystone-app配置到最新主版本：Updates the keystone-app configuration to the newest major version。即生成的工程清单（starter 中名为keystone-app的 package.json，当前版本 1.0.3）及其配置结构升级到与新版 Keystone 兼容；
纯 Node ESM：Changes package to exclusively Node ESM。此包改为纯 ESM 发布，设计上供require(esm)使用，对普通消费者而言主要影响是需要较新的 Node 版本；同时明确声明keystone build的构建产物仍然是 CommonJS，不影响生成项目的部署形态。当前 package.json 中"type": "module"正是这一变更的直接体现。

11.0.1 —— 对齐 UI 版本

Updates@keystar/uito0.9.2to align with@keystone-6/core

将@keystar/ui更新到 0.9.2，与@keystone-6/core的依赖对齐，避免 UI 组件库版本错位。

11.0.2 —— 精简发布包

Removes declaration maps andsrcfrom published package

从发布产物中移除 declaration maps 和src目录，减小 npm 包体积；结合 package.json 中files字段（dist、starter、cli.js）可知，发布包现在只保留构建产物、模板目录与 bin 入口。

升级与使用注意事项

综合 CHANGELOG 与当前源码，使用或升级到 v11.x 时有以下几点需要留意：

安装依赖方式变了：v11 起 CLI 生成工程后不会自动安装依赖，需按提示手动执行cd <目录> && <你的包管理器> install，随后npm run dev（即keystone dev）启动；
包管理器提示是智能的：只要通过 npm/pnpm/yarn 等启动 CLI，后续指引命令会自动匹配你当前使用的包管理器，这依赖npm_config_user_agent环境变量；
Node 版本要求：由于包已切换为纯 ESM 且面向require(esm)，运行环境需要支持现代 Node 特性；而keystone build的产物仍是 CommonJS，线上部署形态不受影响；
数据库可平滑切换：starter 默认 SQLite（file:./keystone.db），如需切换 PostgreSQL，需安装@prisma/adapter-pg与pg，在keystone.ts中用PrismaPg替换适配器，并同步修改 packages/create/starter/prisma.config.ts 中的datasource.url为process.env.DATABASE_URL；
生产安全边界：starter 中access: allowAll与onConnect自动创建初始用户的逻辑都仅面向开发体验，上线前必须收紧访问控制并移除默认凭据。