宝可梦历险记

VitePress ​

简介 ​

VitePress 使用 Markdown 编写的源内容，生成可以轻松部署在任何地方的静态 HTML 页面

VitePress 作为 VuePress 的孪生兄弟，借助 Vue 3 和 vite，VitePress 提供了明显更好的 DX、更好的生产性能、更精致的默认主题以及更灵活的定制 API

官方 ​

它是搭建文档的 静态站点生成器(SSG) 最佳利器之一

其他静态站点生成器

VuePress、Docusaurus、Astro、Modern.js、docsify、Docz、Nuxt、Jekyll、Hexo、Hugo、idoc、Styleguidist、Storybook、Gatsby、Eleventy、Publii

说明

VitePress是一个仅支持ESM的软件包。不要使用 require() 来导入它，请参考 Vite的故障排除指南

当使用 require 导入一个仅支持 ESM 的包时，会出现以下错误且文件无法被 require 加载

建议你通过以下方式将你的配置文件转换为 ESM 格式：

  • 在邻近的 package.json 中添加 "type": "module"

  • vite.config.js/vite.config.ts 重命名为 vite.config.mjs/vite.config.mts

快速上手 ​

在线体验及调试（StackBlitz 驱动）
https://vitepress.new/

前期工作 ​

必备工具
pnpm / yarn / bun
sh
#安装pnpm
npm install -g pnpm
#查看版本号
pnpm -v
sh
#安装yarn
npm install -g yarn
#查看版本号
yarn -v
sh
#安装yarn
npm install -g bun
#查看版本号
bun -v

安装 ​

安装依赖 ​

在项目目录上方的地址栏，上输入 cmd 回车可以快捷打开

sh
pnpm add -D vitepress
sh
npm i -D vitepress
sh
yarn add -D vitepress
sh
bun add -D vitepress
想安装alpha版本？

如果你想体验新版，不在乎Bug，可以安装，虽然正式版bug也不少

sh
pnpm add -D [email protected]
sh
npm i -D [email protected]
sh
yarn add -D [email protected]
sh
bun add -D [email protected]

*批准命令pnpm

sh
pnpm approve-builds

初始化向导 ​

sh
pnpm vitepress init
sh
npx vitepress init
sh
yarn vitepress init
sh
bun vitepress init
文件位置放在 ./docs

文件夹名新手请参照下面，老手可以自己改

如果你直接回车，则是放在了根目录 ./，那你的 脚本命令 也要修改一下

sh
T   Welcome to VitePress!
|
o  Where should VitePress initialize the config?
|  ./docs
|
o  Site title:
|  宝可梦历险记
|
o  Site description:
|  Pokémon
|
o  Theme:
|  Default Theme
|
o  Use TypeScript for config and theme files?
|  Yes
|
o  Add VitePress npm scripts to package.json?
|  Yes
|
—  Done! Now run npm run docs:dev and start writing.

Theme

Theme 的时候有三种选项：

默认主题：Default Theme (Out of the box, good-looking docs)

默认主题+自定义主题：Default Theme + Customization

自定义主题：Custom Theme

安装组件 ​

Vue

sh
pnpm add -D vue
sh
npm i vue
sh
yarn add -D vue
sh
bun add -D vue

git忽略项 ​

添加 .gitignore 文件，主要用于上传到gitee/github时，忽略这些文件不上传

sh
echo node_modules >> .gitignore
echo cache >> .gitignore
echo dist >> .gitignore

脚本命令 ​

默认不用改，在 package.json 中可以查看

建议

在里面添加一个 "type": "module", ，避免有时出现未知错误

json
{
  "devDependencies": {
    "vitepress": "^1.3.4"
  },
  "packageManager": "[email protected]+sha1.98fe2755061026799bfa30e7dc8d6d48e9c3edf0",
  "type": "module",
  "scripts": { 
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  }
}

Visual Studio Code脚本出现报错请执行这行命令

sh
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

启动 ​

本地启动开发环境，来开发你的网站

sh
pnpm run docs:dev
sh
npm run docs:dev
sh
yarn docs:dev
sh
bun run docs:dev
为什么我启动不了

如果你在 初始化向导 直接回车，使用的是 ./ ，而不是 ./doc，这里就是 pnpm run dev

在其 脚本命令 的 scripts 中也可以看到

生成了一个本地 5173 端口的链接，复制到浏览器打开进行预览

sh
F:\vitepress>pnpm run docs:dev

> @ docs:dev F:\vitepress
> vitepress dev docs


  vitepress v1.6.3

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h to show help

按 Ctrl+C键 即可退出开发模式

我们可以关闭cmd，以后全程用 VScode 了

相关 ​

无特殊情况，不需要了解

拓展：启动端口修改

若无必要，不用修改，需要在 脚本命令 中修改端口

这样就是 8080 端口启动了

json
  "scripts": {
    "docs:dev": "vitepress dev docs --port 8080"
  }
拓展：其他启动命令

你也可以直接调用命令

sh
pnpm exec vitepress dev docs
sh
npx vitepress dev docs
sh
bun vitepress dev docs

静态部署 ​

方式 ​

主要讲一下GitHub，其他的方式都大同小异，更多部署方式可以参考官方文档

说明

常见的静态部署方式，无论你采用哪种，都会先上传到GitHub

名称自定义域名限制缺点
Github page支持空间1G，100G/月国内访问慢，百度不收录
Gitee Pages收费空间1G，100G/月需实名，仓库审查
GitLab Pages支持-国内访问慢
Netlify支持100G/月从GitHub、GitLab、BitBucket拉取
Vercel支持100G/月从GitHub、GitLab、BitBucket拉取
Cloudflare Pages支持-从GitHub、GitLab拉取

Base ​

注意

base必须配置，否则打包会丢失css样式！！

根目录配置 /，那么对应 https://yiov.github.io/

仓库 vitepress 配置 /vitepress/ ，那么对应 https://yiov.github.io/vitepress

我们根据自己的需求，选择相应的的配置

ts
export default defineConfig({
    base: '/', //网站部署的路径，默认根目录
    // base: '/vitepress/', //网站部署到github的vitepress这个仓库里
})

另一个要注意的点，部署到非根目录，你的 Fav图标路径 也要变动一下

ts
export default defineConfig({

  //fav图标
  head: [
    ['link',{ rel: 'icon', href: '/logo.png'}], //部署到根目录
    ['link',{ rel: 'icon', href: '/vitepress/logo.png'}], //部署到vitepress仓库
  ],

})

部署 ​

手动部署 ​

构建完成后，在dist文件夹上传到Github即可

sh
pnpm run docs:build
sh
npm run docs:build
sh
yarn docs:build
sh
bun run docs:build
如果你需要本地预览，可以执行
sh
pnpm run docs:preview
sh
npm run docs:preview
sh
yarn docs:preview
sh
bun run docs:preview

默认的构建输出目录 .vitepress/dist ，将生成的所有文件上传到 Github 即可

说明

如果你还不会使用，请参考教程：Github的注册使用到上传

上传成功后，在GitHub仓库 - 设置 - page里把分支改成main，默认root，保存

等创建成功后即可获得访问链接

自动部署（推荐） ​

点我查看 Github Actions 工作流步骤

在仓库 Actions 里新建一个工作流 中创建一个 deploy.yml 脚本文件

每次你更新代码后，系统会自动给你打包上传并部署

说明

名字可以自定义，不用非得用 deploy ，只要下面配置名和这个一致就行

分支默认是 main

yml
# 构建 VitePress 站点并将其部署到 GitHub Pages 的示例工作流程
#
name: Deploy VitePress site to Pages

on:
  # 在针对 `main` 分支的推送上运行。如果你
  # 使用 `master` 分支作为默认分支，请将其更改为 `master`
  push:
    branches: [main]

  # 允许你从 Actions 选项卡手动运行此工作流程
  workflow_dispatch:

# 设置 GITHUB_TOKEN 的权限，以允许部署到 GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# 只允许同时进行一次部署，跳过正在运行和最新队列之间的运行队列
# 但是，不要取消正在进行的运行，因为我们希望允许这些生产部署完成
concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  # 构建工作
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # 如果未启用 lastUpdated，则不需要
      # - uses: pnpm/action-setup@v3 # 如果使用 pnpm，请取消此区域注释
      #   with:
      #     version: 9
      # - uses: oven-sh/setup-bun@v1 # 如果使用 Bun，请取消注释
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm # 或 pnpm / yarn
      - name: Setup Pages
        uses: actions/configure-pages@v4
      - name: Install dependencies
        run: npm ci # 或 pnpm install / yarn install / bun install
      - name: Build with VitePress
        run: npm run docs:build # 或 pnpm docs:build / yarn docs:build / bun run docs:build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: docs/.vitepress/dist

  # 部署工作
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: build
    runs-on: ubuntu-latest
    name: Deploy
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Git提交GitHub仓库 ​

第一次推送

进入GitHub仓库面板查看一下命令

sh
git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/账户名字/仓库名字.git
git push -u origin main
sh
git add .
git commit -m "推送代码"
git push
sh
git add .
git commit -m "拉取合并"
git pull origin main

参考网站 ​

本站已运行: - 天 - 时 - 分 - 秒

Copyright © 2025 Powered by Gamers VitePress Cloudflare Namecheap umami