如何本地预览 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-generatorprisma-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。参考本项目自带的示例 schemaprisma/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的执行流程是定位 schema调用 Prisma 内部方法getSchemaPath()自动查找schema.prisma找到生成器从 schema 中读取所有 generator确认你声明了 Prisma Docs Generator解析输出路径读取 generator 的output配置或默认值确定要托管哪个目录启动 Express 服务在指定端口提供静态文件整个流程的实现入口在 src/cli.ts 的execute函数中。⚠️ 常见问题与报错排查serve命令的错误提示都非常直白对照下面这张表快速定位问题报错信息原因解决办法No sub command was specified直接运行了命令但没有带serve子命令加上serve如npx prisma-docs-generator serveUnable to find schema.prisma file当前目录找不到schema.prisma到包含prisma/schema.prisma的项目根目录执行Prisma Docs Generator was not specified in the schemaschema 里没有声明 docs 生成器按第 2 步添加generator docs块Unable to resolve output path for the generator无法确定文档输出路径检查generator docs配置是否完整另外提醒如果页面打开是旧内容多半是忘记重新执行npx prisma generate—— 文档是生成时产出的静态文件serve本身不会重新生成。✅ 快速上手清单整个流程浓缩为 4 条命令照着敲即可npm install -D prisma-docs-generator— 安装生成器在prisma/schema.prisma中声明generator docs块npx prisma generate— 生成参考文档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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
