如何用JSDoc 5分钟生成专业API文档网站从安装到第一次输出的快速上手教程【免费下载链接】jsdocAn API documentation generator for JavaScript.项目地址: https://gitcode.com/gh_mirrors/js/jsdocJSDoc 是 JavaScript 生态中最成熟的 API 文档生成器只需在代码注释里写上几个标签一条命令就能把整个项目扫描成带目录、带搜索的静态文档网站。本教程面向新手带你在 5 分钟内完成安装 → 注释 → 生成全流程第一次运行即可看到自己的 API 文档网站。为什么选择 JSDoc零配置起步不用写 YAML不用注册 API注释即文档标签体系成熟param、returns、example等上百种标签覆盖绝大多数场景标签定义可在 packages/jsdoc-tag/lib/definitions/core.js 中查阅模板可替换内置经典模板开箱即用也可通过--template参数换装更现代的 UI官方自证JSDoc 自己的文档就是用 JSDoc 生成的环境准备与一键安装JSDoc 支持 Node.js 稳定版仓库 README 声明兼容 Node 8.15 及更高版本。全局安装推荐新手任意目录可用npm install -g jsdoc项目内安装版本锁定团队协作更安全npm install --save-dev jsdoc 本地安装后命令位于./node_modules/.bin/jsdoc。官方建议用波浪号~3.6.3而非尖括号^3.6.3锁定补丁版本详见 README.md。1分钟生成第一份文档新建一个demo.js在函数上方加上注释这就是 JSDoc 的注释即文档核心/** * 计算两个数的和 * param {number} a 第一个数 * param {number} b 第二个数 * returns {number} 求和结果 */ function add(a, b) { return a b; }然后在终端执行jsdoc demo.js打开浏览器访问out/index.html一个带导航栏的 API 文档网站就诞生了 读懂你的第一次输出JSDoc 会把结果输出到默认的out目录可用-d改名index.html—— 文档首页从这里进入导航每个符号一个 HTML 页面 —— 参数、返回值、示例代码自动排版如果想看解析细节可以加--explain参数打印解析过程加--verbose可输出详细日志。完整的命令行选项清单定义在 packages/jsdoc-cli/lib/flags.js常用项速查如下选项简写作用--destination-d指定输出目录默认./out--template-t指定文档模板包--readme-R把 README 作为文档首页内容--access-a只生成指定访问级别的符号--version-v查看版本号--help-h查看完整帮助常见标签速查让文档更专业注释里用/** ... */包裹的块注释才会被解析。以下 6 个标签覆盖 90% 的日常场景标签用途param {Type} name 描述声明参数及其类型returns {Type} 描述声明返回值example内嵌可运行的使用示例class把注释绑定到类property {Type} name描述类的属性since {Version}标注功能从哪个版本可用进阶技巧给类补充description给废弃接口加deprecated文档会自动带上醒目提示项目级信息author、version、license可写在 README 里生成时用-R README.md引入首页。用 conf.json 固化项目配置命令行选项多了会记不住把配置写进conf.json以后一条jsdoc -c conf.json src/即可。项目自带一份示例配置 packages/jsdoc/conf.json.EXAMPLE包含三个核心段落source—— 控制扫描哪些文件如includePattern匹配.js后缀plugins—— 加载 Markdown 支持等扩展templates—— 调整模板行为比如是否在页面里展示源码项目结构一瞥monorepo 怎么组织JSDoc 仓库是一个 monorepo核心包分工清晰可在 package.json 中查看依赖关系packages/jsdoc/ —— 命令行入口即你执行的jsdoc命令入口脚本见 jsdoc.jspackages/jsdoc-core/ —— 文档生成引擎与环境配置packages/jsdoc-tag/ —— 标签解析与类型校验packages/jsdoc-template-legacy/ —— 经典文档模板HTML 模板位于 tmpl/ 目录想深入某个环节直接打开对应包的README.md即可。常见问题快速排查1. 生成的文档是空白页确认用的是块注释/** ... */而非行注释//且注释紧贴在被文档化的函数/类上方。2. 想换更现代的文档风格用--template参数指向社区模板包一条命令即可换肤。3. 私有方法混进文档了给私有符号加private标签或生成时用--access过滤两者任选其一。4. 中文注释显示乱码加-e utf8明确编码默认即为 utf8主要针对旧系统。总结5分钟回顾npm install -g jsdoc安装约30秒在函数上方写/** param ... returns ... */注释约2分钟执行jsdoc 你的文件.js几秒打开out/index.html—— 你的 API 文档网站上线 下一步建议尝试用-R README.md把项目介绍写进首页再用conf.json固化团队配置文档工作流就此成型。【免费下载链接】jsdocAn API documentation generator for JavaScript.项目地址: https://gitcode.com/gh_mirrors/js/jsdoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
