零基础用GitBook搭建个人技术知识库完整教程

准备工作：装好Node.js和Git

搭建GitBook之前需要准备好两个基础工具：Node.js（运行环境）和Git（版本管理）。
这两个工具在所有操作系统上都支持，安装步骤简单。

• Node.js：访问官网 nodejs.org 下载LTS版本（左侧稳定版），双击安装包一路点“下一步”即可。安装完成后打开终端（Windows用CMD或PowerShell，Mac/Linux用终端），输入 node -v 出现版本号说明成功。
• Git：同样去 git-scm.com 下载对应系统的安装包，安装时保持默认选项。完成后在终端输入 git --version 确认版本。

如果你用的是宝塔面板或云服务器，也可以通过包管理器安装：

# Ubuntu/Debian
sudo apt update && sudo apt install nodejs git -y

# CentOS/RHEL
sudo yum install epel-release -y && sudo yum install nodejs git -y

安装GitBook命令行工具

准备就绪后，用npm（Node.js自带的包管理器）全局安装GitBook CLI：

npm install -g gitbook-cli

这个过程会下载GitBook核心库，初次安装可能需要几分钟，请耐心等进度条走完。
安装完成后用 gitbook -V 查看版本，如果输出版本号则表示安装成功。

如果遇到 EACCES 权限错误，可以尝试 sudo npm install -g gitbook-cli（Mac/Linux）或以管理员身份运行CMD（Windows）。

初始化知识库并配置

安装完CLI后，下面创建第一个知识库项目。

1. 新建文件夹并进入

   mkdir my-knowledge-base
   cd my-knowledge-base

1. 初始化GitBook

   gitbook init

执行后文件夹内会生成两个关键文件：README.md（首页内容）和 SUMMARY.md（目录结构）。
可以先用编辑器打开 README.md 写上欢迎语，比如 # 我的技术知识库。

1. 编辑目录结构（SUMMARY.md）

   # Summary
   * [简介](README.md)
   * [服务器基础](server/README.md)
     * [Linux常用命令](server/linux-commands.md)
     * [Nginx配置](server/nginx.md)
   * [建站实战](site/README.md)

每个条目对应一个Markdown文件。
根据规划创建对应文件夹和文件即可。

1. 本地预览

   gitbook serve

启动后终端会提示 Serving book on http://localhost:4000，打开浏览器访问就能看到实时渲染的效果。
修改任意Markdown文件后，浏览器会自动刷新。

如果想把知识库生成静态HTML并发布到服务器，
可以运行 gitbook build，
生成的静态文件默认放在 _book 文件夹，
直接上传到Nginx或Apache的网站目录就能访问。

常见报错与避坑要点

1. gitbook serve 卡住或报错 EACCES: permission denied

这是权限问题，尝试用 sudo gitbook serve（Mac/Linux）或关闭杀软后以管理员运行CMD（Windows）。
如果还是报错，可能是全局node_modules权限不对，可以执行：

sudo chown -R $(whoami) ~/.npm

2. 安装时提示 Error: Cannot find module 'internal/util/types'

通常是Node.js版本过旧或过新。
GitBook CLI对Node.js 10.x～12.x支持最好。
可以用 nvm（Node Version Manager）切换版本：

nvm install 12.22.12
nvm use 12.22.12

然后再重新运行 npm install -g gitbook-cli。

3. 中文乱码或排版问题

确保所有Markdown文件保存为 UTF-8 编码，且文件头部不要加BOM。
Windows记事本保存时选择“UTF-8”即可，推荐使用VS Code或Sublime Text。

4. 外部链接或图片无法加载

GitBook默认使用相对路径。
图片建议放在 assets/images/ 文件夹，引用时写 ../assets/images/xxx.png。
如果是站外链接，直接写完整URL。

验证知识库效果与后续扩展

搭建完成后，可以按以下清单逐项检查：

• [ ] 执行 gitbook serve 后浏览器访问 http://localhost:4000 能正常显示主页。
• [ ] 点击目录中的每个链接，页面跳转正常，内容无断裂。
• [ ] 修改任意 .md 文件，浏览器自动刷新并更新内容。
• [ ] 运行 gitbook build 后 _book 文件夹大小正常，没有报错信息。
• [ ] 将 _book 上传到服务器网站目录后，通过公网IP能访问。

验证通过后，你还可以：

• 使用 GitBook的插件（如 expandable-chapters、page-toc-button）增强交互。在根目录创建 book.json 文件，写入插件配置：

  {
    "plugins": ["expandable-chapters", "page-toc-button"]
  }

然后运行 gitbook install 安装插件。

• 配合 GitHub Pages 或 Vercel 实现自动部署：每次推送Git仓库后自动更新线上文档。

如果你在“GitBook搭建个人技术知识库”的过程中遇到其他问题，欢迎在评论区留言，我会及时补充常见场景的解决方案。