愈合笔记

外观

VuePress 2 快速上手

约 585 字大约 2 分钟

2026-09-08

VuePress 2 正式版发了一段时间了,相比 1.x 的最大变化是:Vite + Vue 3 + TypeScript。本文从零开始,搭一个能写能发的小站。

初始化

新建一个目录,初始化 package.json,装依赖:

mkdir yuhe-blog && cd yuhe-blog
pnpm init
pnpm add -D vuepress@^2.0.0 \
  @vuepress/bundler-vite@^2.0.0 \
  @vuepress/theme-default@^2.0.0 \
  vue@^3.4.0 \
  typescript@^5.4.0

也可以用 npm 或 yarn,只是 pnpm 安装速度更友好。

目录结构

最简的结构长这样:

yuhe-blog/
├── docs/
│   ├── .vuepress/
│   │   └── config.ts
│   ├── posts/
│   │   └── hello-world.md
│   └── README.md
└── package.json
  • docs/ 是站点根目录;
  • .vuepress/config.ts 是配置文件;
  • 其他 Markdown 文件就是页面。

写一份配置

import { defineUserConfig } from 'vuepress'
import { viteBundler } from '@vuepress/bundler-vite'
import { defaultTheme } from '@vuepress/theme-default'

export default defineUserConfig({
  lang: 'zh-CN',
  title: '愈合笔记',
  description: '我在工程、读书、踩坑中留下的可复用笔记',

  bundler: viteBundler(),

  theme: defaultTheme({
    navbar: [
      { text: '首页', link: '/' },
      { text: '归档', link: '/posts/' },
    ],
  }),

  markdown: {
    code: {
      lineNumbers: true,
      highlightLines: true,
    },
  },
})

defineUserConfig 提供了完整的类型提示,写错了会立刻在编辑器里飘红,比 1.x 时代友好太多。

写一篇文章

在 docs/posts/ 下新建 hello-world.md:

---
title: 你好,世界
date: 2026-09-08
tags: [随笔]
---

这是第一篇文章。

\`\`\`ts
const hello = (name: string) => `Hello, ${name}`
\`\`\`

Frontmatter 里的 title 会覆盖文件名,tags 会被默认主题渲染成标签。

启动与构建

在 package.json 的 scripts 加三行:

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs",
    "docs:preview": "vuepress preview docs"
  }
}

执行:

pnpm docs:dev      # http://localhost:8080
pnpm docs:build    # 输出到 docs/.vuepress/dist

dev 端口被占用怎么办

加 --port 8081 指定端口,或者 pnpm docs:dev --port 8081。

部署

构建产物是纯静态文件,扔到任何能托管静态资源的地方都行:

  • GitLab Pages:仓库根目录放 .gitlab-ci.yml,public/ 指向 docs/.vuepress/dist。
  • Nginx:复制 dist/ 到服务器目录,配一份 try_files 规则支持 SPA fallback。
  • 对象存储 + CDN:腾讯云 COS、阿里云 OSS、七牛都支持静态网站托管,记得开启「默认首页」。

几个容易踩的坑

  1. 路径不要写绝对路径。 站点部署在子路径时,相对路径才稳。
  2. Markdown 里 < 开头的内容会被当标签解析。 用 &lt; 转义,或者包在代码块里。
  3. Vite 预构建失败时,先删 node_modules 重装——VuePress 生态还在快速迭代,缓存偶尔会作怪。

就这样,十分钟就能跑起来。