0x00：技术架构概览

核心链路：
VuePress + GitHub Pages + PicGo + 云对象存储 + Markdown 编辑器
（Typora/Obsidian/Yank Note) 三选一即可）

思路：

思路

核心思路图解

前期准备

• Node.js（含 npm）
• Git
• GitHub 账号
• 云厂商对象存储账号（下文以“云存储”代称）

0x01：图床搭建（PicGo + 云存储）

1. 安装 PicGo

1. 进入 PicGo Releases 页面 下载对应平台安装包。

2. 双击安装。

2. （可选）安装 webp 插件

• 打开 PicGo → 插件设置 → 搜索 webp → 安装。

• 上传前自动把图片转成 .webp，省流量、省空间。

  

3. 创建云存储空间

1. 登录云控制台 → 对象存储 → 创建存储桶。

2. 访问权限选择「公有读私有写」（仅做图床）。

   

3. 记录两项信息：

   • 存储桶名称：bucket-name
   • 所属地域：region-code

4. 获取 API 密钥

控制台 → 访问管理 → API 密钥 → 新建密钥 → 保存：

• APPID

• SecretId

• SecretKey

  

  ⚠️ 切勿泄露！如担心主密钥风险，可创建子账号并授予 COS 最小权限。

5. 配置 PicGo 图床

PicGo → 图床设置 → 云厂商 COS：

设为默认图床，并打开上传前重命名，时间戳重命名(2025.8.16 作者注：需要关闭「上传前重命名」，避免弹窗打断无感写作）。

6. 验证上传

• PicGo 上传区 → 选择本地图片 → 上传。
• 成功后可在「相册」看到外链；云控制台也能看到文件。

0x02：Markdown 编辑器对接图床

Typora

文件 → 偏好设置 → 图像：

1. 插入图片时 → 上传图片
2. 上传服务 → PicGo (app)
3. 指定 PicGo 可执行文件路径
   

Obsidian

社区插件 → 搜索 Image auto upload plugin → 安装并启用，默认即可工作。

YankNote

左下角齿轮 → 图片 → 勾选「使用 PicGo 上传」。

0x03：本地 VuePress 站点

1. 安装 Node.js

下载并安装 Node.js (opens new window).

2. 安装依赖

1# 新版本Node.js 自带 npm
2npm install -g yarn          # 全局安装 Yarn
3mkdir my-blog && cd my-blog #新建blog文件夹
4yarn add -D vuepress         # 本地安装 VuePress
5mkdir docs # 新建一个 docs 目录
6echo '# Hello VuePress' > docs/README.md

下面给出面向完全小白的「超详细注释版」教程。
所有命令、配置、字段都加了逐行中文解释，复制即可用。
（已脱敏，图片统一用 <IMG-占位符>）

0x03：本地 VuePress 站点

1. 安装 Node.js

Node.js 是运行 JavaScript 的“发动机”，没它后面的命令都会报错。
下载地址：https://nodejs.org/zh-cn/
安装完重启终端，输入下面两条命令检查是否成功：

1node -v   # 出现 v18.x.x 之类即成功
2npm -v    # 出现 9.x.x 之类即成功

2. 安装依赖

 1# 1. 全局安装 Yarn（包管理器，比 npm 快一点点）
 2npm install -g yarn
 3
 4# 2. 创建项目文件夹并进入
 5mkdir my-kb      # 新建文件夹，名字叫 my-kb（可随意改）
 6cd my-kb         # 进入这个文件夹
 7
 8# 3. 本地安装 VuePress（-D 表示“开发时依赖”）
 9yarn add -D vuepress
10
11# 4. 创建 docs 文件夹（VuePress 规定文章必须放在 docs 里）
12mkdir docs
13
14# 5. 生成一篇最简单的首页
15echo '# Hello VuePress' > docs/README.md

3.配置 package.json

package.json 就像项目的“身份证”，告诉电脑：
“我是谁？需要哪些工具？有哪些快捷指令？”

📄 打开 package.json（用记事本 / VS Code 都行），在最后一个大括号前追加：

1{
2  /* 下面两行就是给命令起“小名”，以后输入小名即可 */
3  "scripts": {
4    "docs:dev": "vuepress dev docs",     // 启动本地实时预览
5    "docs:build": "vuepress build docs"  // 打包成最终网页
6  }
7}

完整示例（可直接覆盖）：

 1{
 2  "name": "my-kb",           // 项目名
 3  "version": "1.0.0",        // 版本号
 4  "description": "我的第一个知识库", // 随便写
 5  "main": "index.js",        // 入口文件，可忽略
 6  "scripts": {
 7    "docs:dev": "vuepress dev docs",
 8    "docs:build": "vuepress build docs"
 9  },
10  "devDependencies": {
11    "vuepress": "^1.9.10"    // 刚刚装的 VuePress
12  }
13}

4. 本地预览

1yarn docs:dev
2# 或
3npm run docs:dev

看到终端最后一行出现 http://localhost:8080 后，
浏览器打开这个地址，就能看见你的第一个网站啦！

0x04：基础美化

📁 推荐的目录结构

1my-kb
2├─ docs               # 所有文章放这里
3│  ├─ README.md       # 首页
4│  └─ .vuepress       # VuePress 专属配置文件夹
5│     └─ config.js    # 网站配置文件
6└─ package.json       # 项目身份证

⚙️ 最简配置文件

新建 docs/.vuepress/config.js，复制以下内容：

 1// 整个文件就是 JavaScript 对象，写错一个标点都会报错
 2module.exports = {
 3  title: '我的知识库',      // 浏览器标签页左上角的大标题
 4  description: '小白也能看懂的 VuePress 教程', // 搜索引擎看到的简介
 5  themeConfig: {
 6    nav: [                   // 顶部导航栏
 7      { text: '首页', link: '/' },        // 点“首页”跳回 /
 8      { text: 'GitHub', link: 'https://github.com/你的用户名/my-kb' }
 9    ],
10    sidebar: [               // 左侧目录树
11      {
12        title: '快速开始',   // 一级菜单名称
13        path: '/',           // 点击后跳转到 /
14        collapsable: false,  // 禁止折叠
15        children: [          // 二级菜单
16          { title: '项目介绍', path: '/' }
17        ]
18      },
19      {
20        title: '进阶指南',
21        path: '/guide/',     // 对应 docs/guide/README.md
22        collapsable: false,
23        children: [
24          { title: '环境搭建', path: '/guide/setup' },
25          { title: '自动部署', path: '/guide/deploy' }
26        ]
27      }
28    ]
29  }
30}

保存后刷新浏览器，就能看到导航栏 + 侧边栏啦！

🎨换主题（可选）

官方默认主题简洁，如果你想要暗黑模式、评论、回到顶部等：

1yarn add -D vuepress-theme-reco

然后在 config.js 最外层加一行：

1module.exports = {
2  theme: 'reco',  // 放在 title 上面或下面都行
3  ...
4}

保存 → 重启 yarn docs:dev，就能看到新主题。

0x05：部署到 GitHub Pages

1. 新建仓库

GitHub → New repository → 名称随意，如 blog

2. 本地仓库初始化

1git init
2git remote add origin https://github.com/<USERNAME>/my-kb.git
3git add .
4git commit -m "init: vuepress site"
5git push -u origin main

3. 自动生成 Token

GitHub → Settings → Developer settings → Personal access tokens → Generate new token (classic)
勾选 repo 权限，生成后复制保存。

4. 配置 Secrets

仓库 → Settings → Secrets → New repository secret
Name: ACCESS_TOKEN
Value: <刚才生成的 Token>

设置好之后效果：

5. GitHub Actions 自动部署

仓库 → Actions → New workflow → 创建 .github/workflows/deploy.yml

 1name: Deploy GitHub Pages
 2
 3on:
 4  push:
 5    branches: [ main ]
 6
 7jobs:
 8  build-and-deploy:
 9    runs-on: ubuntu-latest
10    steps:
11      - uses: actions/checkout@v3
12
13      - name: Setup Node
14        uses: actions/setup-node@v3
15        with:
16          node-version: 18
17
18      - name: Install & Build
19        run: |
20          yarn install
21          yarn docs:build          
22
23      - name: Deploy
24        uses: JamesIves/github-pages-deploy-action@v4
25        with:
26          token: ${{ secrets.ACCESS_TOKEN }}
27          branch: gh-pages
28          folder: docs/.vuepress/dist

6. 启用 Pages

仓库 → Settings → Pages → Source 选择 gh-pages / root → Save。
几分钟后即可通过 https://<USERNAME>.github.io/my-kb 访问。

完结

至此，一套「本地编写 → 图床自动上传 → GitHub 托管 → 自动部署」的低成本知识库闭环搭建完毕。后续只需：

1. 用习惯的 Markdown 编辑器写作。

2. 粘贴图片即自动上传。

3. 更新：

   1git add .
   2git commit -m "更新内容"
   3git push
   

4. 查看 ：5分钟后刷新你的网站地址

💡 从此实现：本地写作 → 自动部署 → 多端同步的知识管理闭环！