精简版-(零基础)如何8个小时内拥有自己的个人网站 (VitePress + Vercel + Cloudflare)

前言：如果你也想拥有一个像 chuanbaozheng.com 这样加载极快、自动生成目录、还能中英双语的个人网站，跟着这份走。不需要你懂编程，只需要你会复制粘贴。
整条链路是：本地写 Markdown → 推送到 GitHub → Vercel 自动部署 → 全球可访问。写完一篇笔记，推一下，一分钟后全世界就能看到。

想看更啰嗦、每一步都配报错处理的版本，去详细版。

第一阶段：准备工作 (工具安装)

在开始之前，你的电脑需要两个"地基"：

Node.js：网站的运行环境。
- 去 nodejs.org 下载 LTS（长期支持版），一路"下一步"装完。
- 装完在 PowerShell 里敲 node -v，能看到版本号就成了。
Git：把代码搬到 GitHub 的搬运工。
- 去 git-scm.com 下载，一路"Next"。
- 装完敲 git --version 验证。
VS Code（可选）：编辑器。
- Windows 自带的 PowerShell + 记事本也能干活，但 VS Code 舒服很多。code.visualstudio.com

第二阶段：初始化你的网站仓库

新建文件夹：比如 my-blog。
打开终端：在这个文件夹里，按住 Shift + 右键 → "在此处打开 PowerShell 窗口"。（或者 VS Code 里 终端 → 新建终端）
运行初始化命令：

bash

npm init -y

bash

npm add -D vitepress vue vitepress-sidebar

bash

npx vitepress init

它会问你几个问题：

问题	怎么答
Where should VitePress initialize the config?	输入 `./`
Site title	你的网站名，如 `XX 的学习空间`
Site description	一句话描述
Theme	选 Default Theme
Use TypeScript for config and theme files?	Yes（选 Yes 才会生成 `config.mts`，跟本文后面的代码对得上）
Add VitePress npm scripts?	Yes

本地预览：

bash

npm run dev

终端会给出 http://localhost:5173，浏览器打开就能看到网站雏形了。

卡在这一步？ 如果报错 npm : 无法加载文件 ... 因为在此系统上禁止运行脚本，见文末的 troubleshooting。

第三阶段：核心配置文件

这是网站的"大脑"。打开 .vitepress/config.mts，全部替换成下面这段（记得把名字、链接、域名改成你自己的）。

这是起步版配置 —— 单语言、一个自动侧边栏，够你先把站跑起来。我自己站上实际在跑的完整版（双语 + 手写侧边栏 + OG 分享信息）贴在详细版末尾，等你想加功能了再去抄。

import { defineConfig } from 'vitepress'
import { generateSidebar } from 'vitepress-sidebar'

export default defineConfig({
  title: "你的名字",
  description: "一句话描述你的站点",
  base: '/',

  // 🌟 三个新手必开的开关，缺一个都会踩坑：
  cleanUrls: true,        // 网址不带 .html；也顺带解决文件夹 index 在本地 404 的问题
  ignoreDeadLinks: true,  // 笔记里难免有写错的链接，不开这个会直接构建失败
  lastUpdated: true,      // 页面底部显示"最后更新时间"

  appearance: false,      // 暗黑模式开关。true = 有切换按钮；false = 只用亮色

  // 自定义域名后再打开，帮助 Google 收录（没买域名可以先删掉这段）
  sitemap: {
    hostname: 'https://你的域名.com'
  },

  head: [
    ['link', { rel: 'icon', type: 'image/svg+xml', href: '/favicon.svg' }],
  ],

  themeConfig: {
    nav: [
      { text: '首页', link: '/' },
      { text: '关于我', link: '/about-me' },
      { text: '笔记', link: '/logs/' },
    ],

    // 自动扫描 logs/ 文件夹生成左侧目录，不用手写
    sidebar: generateSidebar([{
      documentRootPath: '/',
      scanStartPath: 'logs',
      resolvePath: '/logs/',
      useTitleFromFileHeading: true,      // 用文件里的一级标题做目录名
      useFolderTitleFromIndexFile: true,  // 文件夹里有 index.md 就用它的标题
      collapsed: true,
      hyphenToSpace: true,
      sortMenusByName: true,
    }]),

    outline: { label: '本页目录', level: [2, 3] },
    aside: true,

    socialLinks: [
      { icon: 'github', link: '你的 GitHub 链接' }
    ],

    lastUpdatedText: '最后更新时间',
    footer: {
      message: '你的邮箱',
      copyright: `Copyright © ${new Date().getFullYear()} 你的名字`
    }
  }
})

关于 appearance：我自己的站最后设成了 false。原因是自定义样式一多，亮色暗色两套要各调一遍，维护成本翻倍。你要是就用默认主题，大胆开 true，VitePress 自带的暗色很好看。
关于 sidebar：上面这种 sidebar: generateSidebar([...]) 的写法，只在你全站只有一个自动侧边栏时成立。等哪天你想再手写一个（比如给某个专栏排一个固定顺序的目录），得改成对象形式、把自动的那份用 ... 展开进去，否则两个会互相覆盖。详细版里有完整例子。

建立对应的文件

配置里写了路径，就得有对应的文件，不然点进去是空的：

根目录建 index.md（首页）、about-me.md（关于我）
新建文件夹 logs，里面建一个 index.md 和几篇笔记

刷新浏览器，侧边栏就自动按你的文件夹结构排好了。

放图片

根目录建一个文件夹叫 public（VitePress 专门放静态资源的地方），图片丢进去。

在 Markdown 里引用时路径不写 public：

markdown

![](/test-cat.png)

第四阶段：视觉美化 (CSS)

新建 .vitepress/theme/custom.css：

css

:root {
  --vp-c-brand-1: #4f5fd6;   /* 你的品牌色 */
}

/* 导航菜单靠左，搜索/社交图标留在右边 */
.VPNavBarMenu {
  margin-right: auto !important;
  margin-left: 24px !important;
}

/* 首页大标题小一点，默认有点吵 */
.VPHero .name { font-size: 38px !important; line-height: 44px !important; }
.VPHero .text { font-size: 26px !important; line-height: 32px !important; }

然后新建 .vitepress/theme/index.ts 把它挂上去，否则 CSS 完全不生效（新手最常见的"我明明写了样式却没反应"就是漏了这一步）：

import DefaultTheme from 'vitepress/theme'
import './custom.css'

export default {
  extends: DefaultTheme,
}

第五阶段：先建 .gitignore，再推 GitHub

这一步顺序很重要，先做这个再 git add。 我当初就是没做，node_modules 里五千多个文件被一起提交上去了，后面清理很麻烦。

在根目录新建一个文件，名字就叫 .gitignore（前面有个点），内容：

node_modules/
.vitepress/cache/
.vitepress/dist/
.env.local

为什么：node_modules 是几万个第三方库文件，体积几百 MB，而且 Vercel 会自己根据 package.json 重新装一遍，根本不需要传。
⚠️ 注意 .gitignore 只对还没提交过的文件有效。已经提交上去的，加进 .gitignore 也不会自动消失，得用 git rm -r --cached 文件夹名 手动从记录里摘掉。所以务必先建它。

建好之后再推：

在 GitHub 点右上角 + → New repository，名字 my-blog，Private / Public 都行（选 Private 不影响 Vercel 部署，网站照样公开可访问）。不要勾选任何 "Add README / Add .gitignore" 的初始化选项。
回到 PowerShell：

bash

git init

bash

git add .

bash

git commit -m "first commit"

bash

git remote add origin https://github.com/你的用户名/my-blog.git

bash

git push -u origin main

main 还是 master？ GitHub 现在默认分支叫 main。如果推送报错说分支不存在，先跑 git branch -M main 把本地分支改名，再推。
第一次推送会弹窗让你登录 GitHub，点浏览器授权即可。如果它要你配置身份：
bash
git config --global user.email "你的邮箱@example.com"
bash
git config --global user.name "你的名字"

以后每次更新，就这三条：

bash

git add .

bash

git commit -m "更新了今天的笔记"

bash

git push

第六阶段：发布上线 (Vercel)

用 GitHub 账号登录 Vercel。
点 Add New → Project，找到你的仓库点 Import。
Vercel 通常能自动识别 VitePress，直接 Deploy。
核心避坑（构建失败时）：如果报 Permission Denied 或构建挂掉，去项目设置里手动指定：
- Install Command：npm install
- Build Command：node node_modules/vitepress/bin/vitepress.js build
- Output Directory：.vitepress/dist
为什么要绕这么一下：直接写 vitepress build 时，Vercel 的 Linux 环境偶尔会因为可执行权限问题找不到命令。绕开快捷方式、直接用 node 调用那个 js 文件，就不看权限了。
怎么确认成功：回 Vercel Dashboard 看项目卡片
- 绿色 Ready = 成功，卡片上还有你网站的预览图
- 蓝色 Building = 正在跑，等一会儿
- 红色 Error / Failed = 失败，点进去看 Build Logs，报错信息直接贴给 AI 问

第七阶段：拥有自己的域名 (.com)

购买：在 Cloudflare 或 Namecheap 买 yourname.com。Cloudflare 是按成本价卖的，不加价。
在 Vercel 添加域名：项目 → Settings → Domains → 输入你的域名 → Add。
按 Vercel 给你的值配 DNS：
⚠️ 一定要用 Vercel 页面上显示给你的那组值，不要抄网上任何教程里的（包括这篇）。
Vercel 现在给不同项目分配不同的地址：老项目多是 A 记录 76.76.21.21，新项目可能是 216.198.79.1 或别的；www 的 CNAME 也从统一的 cname.vercel-dns.com 变成了每个项目独有的一串（形如 d1d4fc829fe7bc7c.vercel-dns-017.com）。填错了验证就是不通过。
照着 Vercel 那张卡片，去域名商后台加两条：
- A 记录：名称 @，内容 = Vercel 显示的 IP
- CNAME 记录：名称 www，内容 = Vercel 显示的那串
Cloudflare 特有的坑：
- 必须去 SSL/TLS 菜单，把加密模式改成 Full（或 Full strict）。否则会无限重定向，网站打不开。
- 那两条记录的小云朵图标建议先点成灰色（DNS only），等 Vercel 验证通过了再决定要不要开橙色代理。

进阶：和 Obsidian 联动

部署成功后，用 Obsidian 直接管理这个文件夹，写笔记的效率会高很多。

打开 Obsidian → 左下角 "Open another vault" → "Open folder as vault" → 选你的 my-blog 根目录。
几个必改的设置：
- Files & Links → Default location for new attachments 改成 Same folder as current file（图片存在笔记旁边，网页才找得到）
- Files & Links → Use [[Wikilinks]] → 关掉（重要！网页只认标准 Markdown 的 [描述](路径)，不认双方括号）
- Editor → Default view mode 设成 Live Preview
装插件 GitHobs，可以直接在 Obsidian 里推送到 GitHub，不用切回终端。

进阶：中英双语

如果想做成双语站（英文在根目录、中文在 /zh/ 下），在 config.mts 里加 locales：

export default defineConfig({
  title: "Your Name",        // 英文（默认语言，网址不带前缀）

  locales: {
    root: { label: 'English', lang: 'en-US' },
    zh: {
      label: '简体中文',
      lang: 'zh-CN',
      link: '/zh/',
      title: '你的名字',
      themeConfig: {
        nav: [
          { text: '首页', link: '/zh/' },
          { text: '关于我', link: '/zh/about-me' },
        ],
      },
    },
  },
  // ... 其余配置
})

然后把中文页放进 zh/ 文件夹（zh/index.md、zh/about-me.md……），根目录放对应的英文页。导航栏会自动出现语言切换器。

坑：VitePress 假设两种语言的路径是对称的。如果某个目录只有中文版没有英文版（比如我的 logs/），在那个页面点语言切换会 404，需要写额外代码拦截。所以要么两边都建，要么就接受那部分只有一种语言。

Troubleshooting

npm : 无法加载文件 xxx\npm.ps1，因为在此系统上禁止运行脚本

Windows 默认禁止执行脚本，放开即可：

开始菜单搜 PowerShell → 右键 → 以管理员身份运行（这一步很重要）
输入：

bash

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

问你确认时输入 Y 回车
关掉管理员窗口，回到原来的普通窗口重新跑命令

改了 custom.css 但网页毫无变化

八成是漏了 .vitepress/theme/index.ts（见第四阶段）。CSS 文件必须被这个入口文件 import 进来才会生效。

本地好好的，Vercel 上点进某个文件夹却 404

检查 config.mts 里有没有 cleanUrls: true。

构建报错 dead link

VitePress 默认把死链当致命错误。加上 ignoreDeadLinks: true。

常用命令速查

命令	作用
`ls`	看当前文件夹里有什么
`cd 路径`	进入某个文件夹，如 `cd C:\Users\chuan\my-blog`
`cd ..`	回到上一层
`npm run dev`	本地预览（改文件会自动刷新）
`npm run build`	本地构建一次，检查会不会报错
`git status`	看哪些文件改了
`git add .` + `git commit -m "..."` + `git push`	三连推送

💡 写给读者的话

"相信自己。"

我做这个站之前，对着终端一片空白，完全不知道自己面对的是什么。一天下来就好了。你也可以。

lab skills

Books

References

精简版-(零基础)如何8个小时内拥有自己的个人网站 (VitePress + Vercel + Cloudflare)

第一阶段：准备工作 (工具安装)

第二阶段：初始化你的网站仓库

第三阶段：核心配置文件

建立对应的文件

放图片

第四阶段：视觉美化 (CSS)

第五阶段：先建 .gitignore，再推 GitHub

第六阶段：发布上线 (Vercel)

第七阶段：拥有自己的域名 (.com)

进阶：和 Obsidian 联动

进阶：中英双语

Troubleshooting

常用命令速查

💡 写给读者的话

精简版-(零基础)如何8个小时内拥有自己的个人网站 (VitePress + Vercel + Cloudflare) ​

第一阶段：准备工作 (工具安装) ​

第二阶段：初始化你的网站仓库 ​

第三阶段：核心配置文件 ​

建立对应的文件 ​

放图片 ​

第四阶段：视觉美化 (CSS) ​

第五阶段：先建 .gitignore，再推 GitHub ​

第六阶段：发布上线 (Vercel) ​

第七阶段：拥有自己的域名 (.com) ​

进阶：和 Obsidian 联动 ​

进阶：中英双语 ​

Troubleshooting ​

常用命令速查 ​

💡 写给读者的话 ​

精简版-(零基础)如何8个小时内拥有自己的个人网站 (VitePress + Vercel + Cloudflare)

第一阶段：准备工作 (工具安装)

第二阶段：初始化你的网站仓库

第三阶段：核心配置文件

建立对应的文件

放图片

第四阶段：视觉美化 (CSS)

第五阶段：先建 .gitignore，再推 GitHub

第六阶段：发布上线 (Vercel)

第七阶段：拥有自己的域名 (.com)

进阶：和 Obsidian 联动

进阶：中英双语

Troubleshooting

常用命令速查

💡 写给读者的话