如何本地预览 Prisma 参考文档：prisma-docs-generator serve 命令完整教程

如何本地预览 Prisma 参考文档：prisma-docs-generator serve 命令完整教程

【免费下载链接】prisma-docs-generatorPrisma generator for automatically generating documentation reference from the Prisma schema.项目地址: https://gitcode.com/gh_mirrors/pr/prisma-docs-generator

prisma-docs-generator是一个 Prisma 生成器，它能从你的schema.prisma自动生成一份漂亮的 API 参考文档，而内置的serve命令可以一键在本地启动静态服务器，让你在浏览器中实时预览这些 Prisma 参考文档。这篇完整教程将带你从零跑通整个流程：安装配置、生成文档、本地预览，以及常见报错的排查方法。

🧭 先认识 prisma-docs-generator：从 Schema 到参考文档

传统做法是手写文档来描述数据模型，但模型一改，文档就过时了。prisma-docs-generator 的思路是：文档直接由 Prisma Schema 生成，每次执行prisma generate时，参考文档都会自动更新，永远和模型保持一致。

它生成的是一个单页 HTML，包含三大板块：

• 模型文档：每个 model 的字段、类型、默认值、关系
• 输入类型 / 输出类型：Prisma Client 可用的 API 类型
• 侧边栏目录（TOC）：点击即可跳转到对应模型，源码逻辑见 src/generator/toc.ts

页面整体布局由 src/printer/index.ts 组装，左侧 1/5 宽度是粘性目录，右侧是正文，代码高亮由 Prism.js 提供。

📦 本地预览前的准备工作

在本地预览之前，你需要先完成三步安装配置。

第 1 步：安装生成器

在你的项目根目录执行：

npm install -D prisma-docs-generator

第 2 步：在 Schema 中声明生成器

打开prisma/schema.prisma，添加一个 generator 块：

generator docs { provider = "node node_modules/prisma-docs-generator" }

如果需要自定义文档输出位置，可以加output属性，默认值是./docs（相对 schema 所在目录，即prisma/docs）。参考本项目自带的示例 schema：prisma/schema.prisma。

另外一个可选配置是includeRelationFields，默认true，设为false可以隐藏关系字段，让文档更简洁：

generator docs { provider = "node node_modules/prisma-docs-generator" includeRelationFields = false }

第 3 步：触发文档生成

npx prisma generate

这条命令会触发所有生成器，prisma-docs-generator 会在输出目录写入index.html和styles/main.css两个文件，核心写入逻辑在 src/index.ts。至此，serve命令所需的静态文件就已经就绪了。

🚀 一键启动本地预览：serve 命令用法

准备工作完成后，只需要一条命令：

npx prisma-docs-generator serve

执行成功后，终端会输出：

Prisma Docs Generator started at http://localhost:5858

在浏览器打开http://localhost:5858，就能看到你的 Prisma 参考文档页面了。

如何切换端口？默认端口是5858（定义在 src/cli.ts），如果端口被占用，用-p或--port参数指定新端口：

npx prisma-docs-generator serve -p 3000

服务基于 Express 实现，它把生成器的输出目录挂载为静态站点，代码见 src/cli.ts 中的ExpressService类。按Ctrl + C（触发 SIGTERM）即可优雅关闭服务。

🔍 serve 命令背后发生了什么

理解它的工作机制，遇到报错时排查会更容易。serve的执行流程是：

1. 定位 schema：调用 Prisma 内部方法getSchemaPath()自动查找schema.prisma
2. 找到生成器：从 schema 中读取所有 generator，确认你声明了 Prisma Docs Generator
3. 解析输出路径：读取 generator 的output配置（或默认值），确定要托管哪个目录
4. 启动 Express 服务：在指定端口提供静态文件

整个流程的实现入口在 src/cli.ts 的execute函数中。

⚠️ 常见问题与报错排查

serve命令的错误提示都非常直白，对照下面这张表快速定位问题：

另外提醒：如果页面打开是旧内容，多半是忘记重新执行npx prisma generate—— 文档是生成时产出的静态文件，serve本身不会重新生成。

✅ 快速上手清单

整个流程浓缩为 4 条命令，照着敲即可：

1. npm install -D prisma-docs-generator— 安装生成器
2. 在prisma/schema.prisma中声明generator docs块
3. npx prisma generate— 生成参考文档
4. npx prisma-docs-generator serve -p 5858— 本地预览

到这里，你就完成了 Prisma 参考文档的本地预览。模型每修改一次、执行一次prisma generate，刷新浏览器即可看到最新的文档，真正做到"文档与模型零时差"。

【免费下载链接】prisma-docs-generatorPrisma generator for automatically generating documentation reference from the Prisma schema.项目地址: https://gitcode.com/gh_mirrors/pr/prisma-docs-generator