使用 create-keystone-app 快速搭建 Keystone 项目：从初始化到运行你的第一个 Headless CMS

后端【免费下载链接】keystoneThe superpowered headless CMS for Node.js — built with GraphQL and React项目地址https://gitcode.com/gh_mirrors/key/keystone点击查看免费下载导读Keystone 是一个基于 Node.js、GraphQL 与 React 构建的 Headless CMS 框架你只需用 TypeScript 描述数据模型List它就会自动生成一套完整的 GraphQL API 与可视化管理界面Admin UI。本篇指南以 getting-started.md 为骨架讲解如何使用官方 CLI 工具create-keystone-app完成项目的初始化、依赖安装、首次启动并深入分析生成的每个文件与脚本的用途。读完本文你将能够从零开始搭建一个带认证、含 User / Post / Tag 三个列表的 Keystone 项目并理解如何进一步切换到 PostgreSQL、自定义列表与字段。Quick Start四条命令完成起步如果你只想最快地体验 Keystone只需要依次执行以下四条命令npm create keystone-applatest cd my-app npm install npm run devnpm create keystone-applatest通过 npm 触发create-keystone-app的初始化流程在当前目录下生成一个包含项目文件的新文件夹cd my-app进入新生成的项目目录npm install安装项目依赖npm run dev以开发模式启动 Keystone。第一条命令执行后CLI 会询问你想把应用生成到哪个目录见下文“Naming your app”随后自动创建项目骨架并输出后续安装与启动的提示。Installing a Keystone instance两种初始化方式打开你惯用的终端Shell先确保当前目录就是你想创建新项目的目录——create-keystone-app会在当前目录下生成一个包含新 Keystone 文件的新文件夹。方式一npm createnpm create keystone-applatestnpm create是npm init的别名形式它会把后面的keystone-applatest解析为 npm 包create-keystone-app并立即执行。方式二npx如果你更习惯显式使用 npx也可以这样npx create-keystone-applatest两种方式在效果上是等价的都会拉取create-keystone-app的最新发布版本并在本地运行它。从源码看CLI 本体位于 packages/create/src/index.ts核心逻辑非常直接它通过meow解析命令行参数支持直接传入目录名create-keystone-app [directory]如果没有传入目录则用enquirer交互式询问“What directory should create-keystone-app generate your app into?”然后把packages/create/starter/目录下的模板文件_gitignore、schema.ts、package.json、prisma.config.ts、tsconfig.json、keystone.ts、auth.ts、README.md逐个复制到目标目录其中_gitignore会被重命名为.gitignore。启动时它还会检查当前create-keystone-app的版本是否落后于 npm 上的最新版并给出升级提示。Naming your app命名应用与自动创建数据库CLI 会要求你为应用命名即上一步中的目录名。命名完成后它会基于模板为项目创建一个 SQLite 数据库默认数据库文件为file:./keystone.db保证你无需任何外部数据库服务即可立刻体验。注意项目创建完成后你可以随时切换到 PostgreSQL 等其他数据库。相关配置方式见下文“切换到 PostgreSQL”小节完整的数据库配置文档在 docs/content/docs/config/ 下的 Config API 文档中。启动与首次登录 Admin UI生成项目后进入新创建的目录、安装依赖并启动 Keystonecd my-app npm install npm run devnpm run dev内部执行的是keystone dev见 packages/create/starter/package.json 中的 scripts 配置。启动成功后Keystone 会通过 Next.js 在 http://localhost:3000 生成 Admin UI 页面项目首次启动时keystone.ts中的onConnect钩子会自动创建一个初始用户并把邮箱地址与随机生成的密码打印到终端见 packages/create/starter/keystone.ts用终端输出的凭据登录后你会看到一个全新的 Admin UI其中自带两个列表listsUser和Post。在 Admin UI 中你可以浏览、增删改查系统中的数据直观地理解 Keystone 的 schema 如何映射到 GraphQL API——你可以在 http://localhost:3000/api/graphql 上直接探索对应的 GraphQL API。上述截图即展示了登录后的 Dashboard左侧导航包含 Users 与 Posts中央卡片分别显示两个列表的记录数与新增入口。OutputCLI 生成的文件结构create-keystone-app会在新项目目录中生成以下文件。其中最重要的两个是keystone.tsKeystone 系统配置入口与schema.ts数据模型定义. ├── auth.ts # Authentication configuration for Keystone ├── keystone.ts # The main entry file for configuring Keystone ├── node_modules # Your dependencies ├── generated/prisma # Generated Prisma Client (ignored by Git) ├── package.json # Your package.json with three scripts prepared for you ├── package-lock.json # Your npm lock file ├── prisma.config.ts # Prisma CLI datasource and migration configuration ├── README.md # Additional info to help you get started ├── schema.graphql # GraphQL schema (automatically generated by Keystone) ├── schema.prisma # Prisma schema (automatically generated by Keystone) ├── schema.ts # Where you design your data schema └── tsconfig.json # Your typescript config对照仓库中的真实模板packages/create/starter/可以逐一确认这些文件的职责keystone.ts—— Keystone 的入口文件默认导出一个config()配置对象其中db配置 SQLite 数据库通过prisma/adapter-better-sqlite3的PrismaBetterSqlite3适配器连接file:./keystone.dblists引入schema.ts导出的列表session引入auth.ts的会话配置并通过withAuth包装启用认证同时内置了apolloConfig插件用于在控制台打印每次 GraphQL 操作的名称与遇到的错误schema.ts—— 数据模型设计文件定义了User、Post、Tag三个列表详见下文auth.ts—— 基于keystone-6/auth的createAuth()配置认证以User列表、email作为身份字段、password作为密钥字段sessionData为name createdAt同时用statelessSessions()配置基于 Cookie 的无状态会话过期时间为 30 天60 * 60 * 24 * 30秒secret读取自环境变量SESSION_SECRETprisma.config.ts—— Prisma CLI 的配置指定 schema 文件为schema.prisma、迁移目录为migrations、数据源 URL 为file:./keystone.dbtsconfig.json—— 项目 TypeScript 配置strict模式、commonjs模块、noEmit详见 packages/create/starter/tsconfig.jsonschema.graphql / schema.prisma—— 由 Keystone 根据schema.ts自动生成前者是暴露给客户端的 GraphQL Schema后者是 Prisma 层的数据库 Schemagenerated/prisma—— 生成的 Prisma Client已被.gitignore忽略不进入版本控制README.md—— 面向新项目的补充说明文档见 packages/create/starter/README.md。Scriptspackage.json 中预置的脚本模板的package.json见 packages/create/starter/package.json为你准备了以下 npm scripts脚本命令作用devkeystone dev在开发模式下运行 Keystone地址为 http://localhost:3000startkeystone start在生产模式下运行 Keystonebuildkeystone build构建项目必须在start之前执行postinstall—确保 Keystone 自动生成的文件如 schema、Prisma Client存在并保持最新其中dev、start、build对应 Keystone CLI 的核心命令postinstall会在每次npm install后自动执行确保keystone.ts所需的生成文件如generated/keystone/types始终存在且与 schema 同步——这正是首次npm install后不需要额外手动生成步骤的原因。关于 Keystone CLI 的更多命令细节可阅读仓库中 docs/content/docs/guides/ 下的命令行指南文档。深入模板starter 自带的三个列表为了让首次体验更有价值starter 的schema.ts见 packages/create/starter/schema.ts内置了三个列表覆盖了 Keystone 最常用的字段类型与关系模式User 列表认证主体User: list({ access: allowAll, fields: { name: text({ validation: { isRequired: true } }), email: text({ validation: { isRequired: true }, isIndexed: unique, }), password: password({ validation: { isRequired: true } }), posts: relationship({ ref: Post.author, many: true }), createdAt: timestamp({ defaultValue: { kind: now } }), }, })要点email通过isIndexed: unique保证唯一性作为登录身份字段password使用password字段类型存储不会明文持久化posts是一对多的关系字段反向引用Post.authorcreatedAt在创建时自动取当前时间。Post 列表内容主体Post: list({ access: allowAll, fields: { title: text({ validation: { isRequired: true } }), content: document({ formatting: true, layouts: [ [1, 1], [1, 1, 1], [2, 1], [1, 2], [1, 2, 1], ], links: true, dividers: true, }), author: relationship({ ref: User.posts, ui: { displayMode: cards, cardFields: [name, email], inlineEdit: { fields: [name, email] }, linkToItem: true, inlineConnect: true, }, many: false, }), tags: relationship({ ref: Tag.posts, many: true, ui: { displayMode: cards, cardFields: [name], inlineEdit: { fields: [name] }, linkToItem: true, inlineConnect: true, inlineCreate: { fields: [name] }, }, }), }, })要点content使用独立的keystone-6/fields-document包提供的document字段支持富文本格式化、多栏布局、链接与分隔线author与tags都是关系字段并通过ui配置在 Admin UI 中以卡片cards形式展示、行内编辑和快速关联。Tag 列表轻量分类Tag: list({ access: allowAll, ui: { hideNavigation: true }, fields: { name: text(), posts: relationship({ ref: Post.tags, many: true }), }, })要点Tag 只有name字段并通过ui.hideNavigation: true隐藏左侧导航入口但仍可通过 Post 内的关系卡片进行管理。关于权限的提醒starter 中的三个列表全部使用access: allowAll即任何人都可以创建、查询、更新和删除数据。这不适合直接对外暴露的生产环境Auth 与访问控制的完整方案在 docs/content/docs/guides/ 下的认证与访问控制指南中。切换到 PostgreSQL替换数据库starter 默认使用 SQLite 以获得最快的启动体验。若要切换为 PostgreSQL按 packages/create/starter/README.md 中的步骤操作npm install prisma/adapter-pg pg然后在keystone.ts中导入PrismaPg并替换db配置import { PrismaPg } from prisma/adapter-pg db: { provider: postgresql, prismaClientOptions: () ({ adapter: new PrismaPg({ connectionString: process.env.DATABASE_URL! }), }), }同时把 prisma.config.ts 中的datasource.url改为process.env.DATABASE_URL。需要理解的关键点是Prisma CLI 在跑迁移时从prisma.config.ts读取连接串而 Keystone 运行时使用上面配置的 adapter两者职责不同都需要同步修改。Where to next下一步方向完成本篇指南的流程后你的 Keystone 项目已经可以运行。接下来可以按需深入使用 System Configuration API 定制系统配置如数据库、GraphQL、会话、缓存等使用 Lists API 添加更多字段与关系字段类型概览在 docs/content/docs/fields/使用 Config API 中的db配置切换到 PostgreSQL 等其他数据库阅读 Keystone CLI Guide掌握dev/build/start等命令的完整用法参考仓库中的 examples/ 目录里面有大量可直接运行的示例工程认证、自定义字段、扩展 GraphQL、不同前端框架接入等例如 examples/auth/ 演示了完整的认证配置、examples/framework-nextjs-app-directory/ 演示了在 Next.js App Router 中消费 Keystone 的 GraphQL API。赞分享后端【免费下载链接】keystoneThe superpowered headless CMS for Node.js — built with GraphQL and React项目地址https://gitcode.com/gh_mirrors/key/keystone点击查看免费下载相关推荐使用 Yeoman 生成器快速搭建 Keystone 项目yo keystone 完整实战指南使用 Yeoman 生成器快速搭建 Keystone 项目yo keystone 完整实战指南 Keystone 是一个基于 Node.js 与 MongoD后端使用 TypeScript 快速搭建 Node.js 项目从初始化到实时编译运行使用 TypeScript 快速搭建 Node.js 项目从初始化到实时编译运行 导读 本文基于开源书籍仓库 typescript book https://教程如何为 SpacetimeDB 应用接入 Auth0 登录如何为 SpacetimeDB 应用接入 Auth0 登录 这篇文章面向已经完成 SpacetimeDB 快速开始、手里有一个可运行的 React Spac后端上一篇如何用 Gridism 实现响应式布局移动端自动堆叠的 3 个关键技巧下一篇libiec61850实战指南构建电力系统通信解决方案的完整路径创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考