xiaoyu博客

主题

2026年 元旦 倒计时
0天 0时 0分 0秒
——小鱼🐬

写在前面 ​

人会死，但我的博客在GitHub中会万岁 ​

博客是一个分享经验、表达情感的地方，最重要的就是能够随心记录点点滴滴。

当人类面对时间的无情流逝，我们总是渴望留下一些痕迹，一些思想，一些记忆。博客，作为一种数字化的表达方式，成为了我们记录自己、分享见解、传承知识的平台。然而，时间也在不断地削弱这些数字化的痕迹，让它们逐渐消失在虚拟的海洋中。

一、博客的起源 ​

我的博客之旅始于多年前的QQ空间。那时，QQ空间也支持一定程度的页面定制化，各种杀马特的装饰与那时流行的非主流个性签名相得益彰，令人惊艳不已。

然而，随着时间的流逝，我发现原来还有更多的可能性可以探索。拥有自己的域名，搭建一个自由度更高的个人独立博客成为了我的新目标。于是，我开始尝试着使用WordPress、Typecho、Hexo等各种框架。虽然在更换框架时，有一些可以导出导入的功能，但是不可避免地会出现一些文章和图片丢失的情况。

这个过程不仅是技术上的探索与挑战，更是一个个人成长与思想表达的历程。从QQ空间到拥有自己独立域名的博客，我逐渐意识到，在数字世界中，我们可以拥有更多的自由和创造力，去塑造和展示自己的独特风格和观点。因此，尽管在博客之路上曾经遇到过一些挫折，但每一次的尝试和探索都让我更加坚定了继续前行的决心。

二、博客的长寿之道 ​

关于选择独立搭建博客还是选择购买个人博客服务的讨论比比皆是。究其根本，如果有免费、稳定的空间搭建独立博客，且安装部署简单、后续维护简洁、使用过程方便，那就不需要购买别人提供的博客服务了。

随着云服务的普及，搭建一个廉价、甚至是免费的独立博客已经不再是只有“高手”才能玩的了，我们只需要自己动手就能搭建。

考虑到个人购买服务器并不是长久之计，我转而关注了GitHub Pages。正如《People Die, but Long Live GitHub》这篇文章所述，如果我们希望存储一段信息，让100年后的人也能够轻松访问，应该采取怎样的策略呢？GitHub Pages提供了一个免费、稳定的托管平台，使你的博客与GitHub的存在时间同步。这意味着，无论是作为个人创作的见证，还是作为技术成果的展示，你的博客都能够以一种更加持久的方式存在，并为未来的读者提供信息与启发。因此，将博客托管于GitHub Pages不仅是一种技术选择，更是一种长寿的智慧之举。

三、关于选型 ​

博客框架在互联网上琳琅满目，有php、java、go、node等各种语言搭的。功能齐全，包括了前端，管理后端。还提供各种精美主题选择。

相信每个web开发的程序员都曾经搭建过个人博客，然后租个服务器托管，然后写了一两篇文章，阅读量也并不多。渐渐的不再维护，热度逐渐消失，最后服务器到期关站。

我曾经也是这类人之一，兜兜转转，我倒是觉得写博客还是应该追求极简主义、返璞归真。其实就应该直接用静态站点生成一个项目，找个免费的云端托管。写文章时直接用自己趁手的工具用markdown语法，写完提交代码就完事了，发布也是把打包文件提交就ok了。

不再去最求那些花里胡哨的主题和框架后，你反而能够安安心心写一些文章了，点滴滴滴也是积累。

四、关于搭建 ​

本博客就是使用vitepress直接搭建的，搭建过程非常简单，托管服务是使用的vercel免费托管静态站点，想要域名访问就买个便宜域名，解析到vercel就完事了。 不需要托管费用，图床也省了，速度也有保障。

1. 前置准备 ​

  1. VitePress 可以单独使用，也可以安装到现有项目中。在这两种情况下，都可以使用以下方式安装它：
sh
$ npm add -D vitepress
sh
$ pnpm add -D vitepress
sh
$ yarn add -D vitepress
sh
$ yarn add -D vitepress vue
sh
$ bun add -D vitepress
遇到了 missing peer deps 警告？

如果使用 PNPM，会注意到对 @docsearch/js 的 missing peer deps 警告。这不会影响 VitePress 运行。如果希望禁止显示此警告，请将以下内容添加到 package.json：

json
"pnpm": {
  "peerDependencyRules": {
    "ignoreMissing": [
      "@algolia/client-search",
      "search-insights"
    ]
  }
}

注意

VitePress 是仅 ESM 的软件包。不要使用 require() 导入它，并确保最新的 package.json 包含 "type": "module"，或者更改相关文件的文件扩展名，例如 .vitepress/config.js 到 .mjs/.mts。更多详情请参考 Vite 故障排除指南。此外，在异步 CJS 上下文中，可以使用 await import('vitepress') 代替。

2. 安装向导 ​

VitePress 附带一个命令行设置向导，可以帮助你构建一个基本项目。安装后，通过运行以下命令启动向导：

sh
$ npx vitepress init
sh
$ pnpm vitepress init
sh
$ yarn vitepress init
sh
$ bun vitepress init

将需要回答几个简单的问题：

Vue 作为 peer dependency

如果打算使用 Vue 组件或 API 进行自定义，还应该明确地将 vue 安装为 dependency。

注意

如果上面的npx vitepress init报错，直接忽略，手动新建文件夹，没有影响。注意一下文件结构就可以了。

3. 文件结构 ​

如果正在构建一个独立的 VitePress 站点，可以在当前目录 (./) 中搭建站点。但是，如果在现有项目中与其他源代码一起安装 VitePress，建议将站点搭建在嵌套目录 (例如 ./docs) 中，以便它与项目的其余部分分开。

假设选择在 ./docs 中搭建 VitePress 项目，生成的文件结构应该是这样的：

.
├─ docs
│  ├─ .vitepress
│  │  └─ config.js
│  ├─ api-examples.md
│  ├─ markdown-examples.md
│  └─ index.md
└─ package.json

docs 目录作为 VitePress 站点的项目根目录。.vitepress 目录是 VitePress 配置文件、开发服务器缓存、构建输出和可选主题自定义代码的位置。

提示

默认情况下，VitePress 将其开发服务器缓存存储在 .vitepress/cache 中，并将生产构建输出存储在 .vitepress/dist 中。如果使用 Git，应该将它们添加到 .gitignore 文件中。也可以手动配置这些位置。

下面是我自己在Github上,根目录docs下，安装的vitepress 。我想把vitepress安装到vite文件夹中，替换了官方的docs文件夹。避免了 docs/docs混淆，于是重新命名了 。

vitepress更换路径后需要更改根目录下的package.json文件，具体下面再讲。


yf20230412.github.io/
 .
├── package.json
├── .gitignore
├── node_modules
├── .github
│   └── workflows/deploy.yml
├── docs/
│   ├── ...
│   ├── docs/
│   │   ├── .vitepress/
│   │   │   ├── config.mjs
│   │   │   └── ...
│   │   ├── index.md
│   │   └── ...
│   └── bk/

4. 配置文件 ​

配置文件 (.vitepress/config.js) 让你能够自定义 VitePress 站点的各个方面，最基本的选项是站点的标题和描述：

js
export default {
  // 站点级选项
  title: 'VitePress',
  description: 'Just playing around.',

  themeConfig: {
    // 主题级选项
  }
}

还可以通过 themeConfig 选项配置主题的行为。

插件安装，如何配置网上找教程

  • 全局公告窗口插件，用来弹窗
pnpm add vitepress-plugin-announcement
  • （不蒜子）插件来统计页面浏览量
pnpm add -D busuanzi.pure.js
  • 纸屑粒子
pnpm add canvas-confetti
  • Giscus评论
pnpm add @giscus/vue

5. 源文件 ​

.vitepress 目录之外的 Markdown 文件被视为源文件。

VitePress 使用 基于文件的路由：每个 .md 文件将在相同的路径被编译成为 .html 文件。例如，index.md 将会被编译成 index.html，可以在生成的 VitePress 站点的根路径 / 进行访问。

VitePress 还提供了生成简洁 URL、重写路径和动态生成页面的能力。

6. 启动并运行 ​

package.json官方填写格式：

json
{
  ...
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  },
  ...
}

docs:dev 脚本将启动具有即时热更新的本地开发服务器。使用以下命令运行它：

sh
$ npm run docs:dev
sh
$ pnpm run docs:dev
sh
$ yarn docs:dev
sh
$ bun run docs:dev

除了 npm 脚本，还可以直接调用 VitePress：

sh
$ npx vitepress dev docs
sh
$ pnpm vitepress dev docs
sh
$ yarn vitepress dev docs
sh
$ bun vitepress dev docs

本地预览 启动本地开发服务器,浏览器输入 http://localhost:5173 查看配置文件。

.vitepress/dist 作为源文件,预览构建文件 ,浏览器输入http://localhost:4173/ 查看构建文件。

更换路径后需要更改根目录 { 可结合上面的步骤3 }：

js
"scripts": {
    "dev": "vitepress dev docs/vite",
    "build": "vitepress build docs/vite && npm run move-dist",
    "preview": "vitepress preview docs/vite",
    "move-dist": "rm -rf docs/bk/* && cp -R docs/vite/.vitepress/dist/* docs/bk/"
  },

解释

  • build 脚本：

    • vitepress build docs/vite：构建文档，生成的文件会放在 docs/vite/.vitepress/dist 目录中。

    • npm run move-dist：运行 move-dist 脚本，将构建输出移动到 docs/bk 文件夹中。

  • move-dist 脚本：

    • rm -rf docs/bk/*：删除 docs/bk 文件夹中的所有内容（注意：这会删除 docs/bk 文件夹中的所有文件，确保这是你想要的操作）。

    • cp -R docs/vite/.vitepress/dist/* docs/bk/：将 docs/vite/.vitepress/dist 中的所有文件复制到 docs/bk 文件夹中。

注意事项

  • 备份重要文件：

    • 在运行 npm run build 之前，确保备份 docs/bk 文件夹中的重要文件，因为rm -rf docs/bk/* 会删除该文件夹中的所有内容。

  • 测试构建过程：

    • 在本地运行 npm run build，确保构建过程没有问题，并且生成的文件正确地放置在 docs/bk 文件夹中。

示例：GitHub Actions 配置

如果你使用GitHub Actions自动部署，确保 .github/workflows/deploy.yml文件中正确地运行了npm run build 命令，并且部署目录是 docs/bk。以下是修改后的 GitHub Actions配置示例：

以下构建需要满足下面条件,方可部署成功

  • 选择GitHub Pages 的 branch/docs 部署方式

    • **GitHub Pages **设置中选择 Deploy from a branch -> 分支选择 main/master，目录选择 /docs

::: warning注意： 进制使用 GitHub Actions 上传 artifact 方式 :::

    • VitePress 的 base: '/bk/' (确保资源路径正确)
"scripts": {
    "dev": "vitepress dev docs/docs",
    "build": "vitepress build docs/docs",
    "preview": "vitepress preview docs/docs"
  }
yaml
name: Deploy VitePress to Branch

on:
  push:
    paths:
      - 'docs/docs/**'
  workflow_dispatch:

env:
  TZ: Asia/Shanghai

permissions:
  contents: write # 需要写权限提交代码

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      # 检出代码
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      # 配置 Node 环境
      - uses: pnpm/action-setup@v3
        with:
          version: 9      
          
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm

      # 修复可能的权限问题
      - name: Fix permissions
        run: sudo chown -R $USER:$USER .

      # 安装依赖
      - name: Install dependencies
        run: pnpm install

      # 清理旧构建
      - name: Clean
        run: rm -rf docs/docs/.vitepress/dist

      # 构建 VitePress
      - name: Build
        run: pnpm run build

      # 移动构建产物到目标目录
      - name: Move Artifacts
        run: |
          echo "=== 开始移动构建产物 ==="
          
          echo "源目录结构："
          ls -lR docs/docs/.vitepress/dist
          
          echo "目标目录原始状态："
          ls -la docs/bk/ || echo "目录不存在（这是正常现象）"
          
          echo "创建目标目录..."
          mkdir -p docs/bk
          echo "创建后权限："
          ls -ld docs/bk
          
          echo "清理旧文件..."
          rm -rfv docs/bk/*
          
          echo "复制新文件（详细列表）..."
          cp -Rv docs/docs/.vitepress/dist/* docs/bk/
          
          echo "复制后验证："
          echo "目标目录大小："
          du -sh docs/bk
          echo "目标目录文件数："
          find docs/bk/ -type f | wc -l
          echo "关键文件检查："
          ls -l docs/bk/index.html docs/bk/assets/*
          
          echo "=== 移动完成==="

      # 自动提交变更
      - name: Commit changes
        run: |
          git config --global user.name "替换仓库用户名"
          git config --global user.email "替换你的邮箱"
          git add docs/bk/
          if git diff --staged --quiet; then
            echo "无需提交任何更改."
          else
            git commit -m "自动部署"
            git push origin HEAD:${{ github.ref }}
          fi
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

简化版《自动把构建产物复制到docs/bk目录》

yaml
name: Deploy VitePress to Branch

on:
  push:
    paths:
      - 'docs/docs/**'
  workflow_dispatch:

env:
  TZ: Asia/Shanghai

permissions:
  contents: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      # 配置 Node 环境
      - uses: pnpm/action-setup@v3
        with:
          version: 9      
          
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm

      - name: Fix permissions
        run: sudo chown -R $USER:$USER .

      - name: Install dependencies
        run: pnpm install

      - name: Clean
        run: rm -rf docs/docs/.vitepress/dist

      - name: Build
        run: pnpm run build

      - name: Move Artifacts
        run: |
          echo "=== 开始移动构建产物 [$(date '+%Y-%m-%d %H:%M:%S')] ==="
          mkdir -p docs/bk
          rm -rfv docs/bk/*
          cp -Rv docs/docs/.vitepress/dist/* docs/bk/
          echo "=== 移动完成 ==="

      - name: Commit changes
        run: |
          git config --global user.name "Auto Deploy"
          git config --global user.email "[email protected]"
          git add docs/bk/
          if git diff --staged --quiet; then
            echo "No changes to commit."
          else
            git commit -m "Auto-deploy: $(date +'%Y-%m-%d %H:%M:%S')"
            git push origin HEAD:${{ github.ref }}
          fi
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

详细注释

触发条件

yaml
on:
  push:
    paths:
      - 'docs/vite/'
  workflow_dispatch:
  • push: 仅在推送到 docs/vite 文件夹时触发工作流。
  • workflow_dispatch: 允许手动触发工作流，例如通过 GitHub Actions 的 Web 界面。

环境变量

并发控制

yaml

concurrency:
  group: pages
  cancel-in-progress: false
  • group: pages: 将所有相关的工作流归为一个组，避免并发冲突。
  • cancel-in-progress: false: 如果有正在进行的相同工作流，不取消。

构建工作

yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
  • Checkout: 检出代码，确保获取完整的提交历史。
yaml
      - uses: pnpm/action-setup@v3
        with:
          version: 9
  • pnpm/action-setup@v3: 设置 pnpm 环境，使用 pnpm 9。
yaml
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
  • actions/setup-node@v4: 设置 Node.js 环境，使用 Node.js 20，并启用 pnpm 缓存。
yaml
      - name: Move build output to docs/bk
        run: npm run move-dist
  • npm run move-dist: 将构建产物从 docs/vite/.vitepress/dist 移动到 docs/bk 。
yaml

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./docs/bk
  • actions/upload-pages-artifact@v3: 将构建产物上传为 GitHub Pages 的部署内容。
yaml
    - name: Send deployment notification
      uses: dawidd6/action-send-mail@v2
      with:
        server_address: smtp.example.com
        server_port: 587
        username: [email protected]
        password: ${{ secrets.EMAIL_PASSWORD }}
        subject: "Deployment Notification"
        body: "The site has been deployed to ${{ steps.deployment.outputs.page_url }}"
        to: "邮箱@163.com"
  • dawidd6/action-send-mail@v2: 使用第三方邮件发送动作发送部署通知。
  • server_address: SMTP 服务器地址。
  • server_port: SMTP 服务器端口。
  • username: 发件人邮箱。
  • password: 发件人邮箱密码（存储在 GitHub Secrets 中）。
  • subject: 邮件主题。
  • body: 邮件内容，包含部署后的网站 URL。
  • to: 收件人邮箱。

7.上传文件 ​

.md 格式博客文件上传到 docs/vite/blog 文件夹

修改配置：

  • 首页也就是中间导航栏，修改 docs/vite/blog/index.md 文件。

  • 左侧导航栏，修改 vite/.vitepress/menu/sidebar.ts 文件。

  • 右侧导航栏， 修改 vite/.vitepress/menu/navbar.ts 文件。

  • 主题插件（全局生效）特效 vite/.vitepress/theme 文件夹

  • 插件（需要单独引用） vite/.vitepress/components 文件夹

特效

  • 纸屑

    • <confetti />

  • 文章更新时间插件

    • <LastUpdated />

使用方法：放到文章最底部

配置插件GitHub
  1. 配置依赖 在package.json文件中dependencies位置添加依赖插件信息。格式如下
"dependencies": {
    "canvas-confetti": "^1.9.3",
    "vitepress-plugin-announcement": "^0.1.4",
    "@giscus/vue": "^3.1.1"
  }
  1. 更新pnpm-lock.yaml文件 删除pnpm-lock.yaml文件，手机上因为权限问题，需要将vitepress文件移动到Termux根目录上即 cd /data/data/com.termux/files/home/ 目录。cd到目录，运行以下代码，重新生成新的pnpm-lock.yaml文件，上传到GitHub上使用。
pnpm install

五、如何搭建 ​

搭建过程会在下一篇详细描述，敬请期待。

六、参考链接 ​

vitepress官方文档：https://vitepress.dev/zh/

vercel官方网站：https://vercel.com/home

基本美化步骤：https://blog.csdn.net/weixin_44803753/article/details/130903396

教你用VitePress搭建博客：https://xuxing409.github.io/my-blog/technology/article/building-blog-with-vitepress.html

掘金搭建教程: https://juejin.cn/post/7409865546197893171

其它教程: https://vitepress-sidebar.cdget.com/zhHans/guide/getting-started

七、博客的未来 ​

虽然没有什么东西是真正永恒的，但我们可以尽力让自己的博客在这个数字时代中存活更久，成为我们留给世界的一份礼物。让我们珍惜这个数字化的痕迹，让它们在 GitHub 中长寿不衰。

《风言锋语88》

Copyright © 2024- Xiao yu