详细版-零基础-如何8个小时内拥有自己的个人网站

chuanbaozheng.com

20260325 今天决定建立自己的个人网站； 原因是昨天我老婆做了一个网站；我做自己网站的心思最早始于硕士期间。等由于一些知识壁垒加上拖延，迟迟没有做。

于是；像一个积累到一定程度的火山，我决定今天摸索一下。 毕竟早上起来；自己一点都不知道；对自己的面临的敌人和困难没有任何的概念。 Anyways；尽然我可以；你都看到这里了，相信自己，你一定也可以！

本文是详细版，每一步都拆开写、带报错处理。如果你只想要一份能直接抄的配置，看 精简版。

（2026-07 更新：这篇最早写于 2026-03。这次按站点的实际情况重新校对了一遍，修掉了几处照着做会卡住的地方 —— 主要是 GitHub 默认分支名、Vercel 的 DNS 数值、以及一个我自己踩了的 .gitignore 坑。）

---

需要的工具

创造网站主要是以下这条 pipeline：

本地写代码 → 推送到 GitHub → Vercel 自动部署 → 全球生成网址

开始之前，先把下面这些账号注册好：

Number	Tools	link	comments	翻译成人话
	Computer		有一个可以创建文件夹的电脑
1	Gemini / ChatGPT / Claude	https://gemini.google.com/	报错了贴给它，让它帮你解	你的随身技术支持
2	Github	https://github.com/	本地构建的代码上传到 GitHub；下一个软件(Vercel)就能够调用
3	Vercel	https://vercel.com	用于部署网站；把 GitHub 上存的内容发布到万维网上
4	Windows PowerShell	免安装，windows 电脑自带	这个不用安装	需要了解一些基础的 command line
5	Obsidian	https://obsidian.md/	能和 PowerShell 联动；实现把你刚更新的内容上传到 GitHub 上	可选，但强烈推荐
6	Git	https://git-scm.com/download/win	代码搬运工；这个可以晚点安装，在第 14 步的时候	不急
7	Cloudflare	https://dash.cloudflare.com	注册和购买域名	自定义域名

好的，咱们开始：

---

第一部分：本地把网站跑起来

1. 先安装 Node.js，目的是你在正式上传你的网站之前，能够本地预览：https://nodejs.org/ 下载 LTS 版，一路"下一步"。

2. 装完后，按 win 键（四个小方块），搜索 Windows PowerShell，打开。你会看到类似这样的提示符：

PS C:\Users\chuan>

3. 输入 cd Desktop（进入桌面文件夹）。

这一步如果遇到错，可以把报错原样贴给 AI 让它帮你解决。

4. mkdir my-blog （创建一个名字叫 my-blog 的文件夹）

5. cd my-blog （进入 my-blog 这个文件夹）

6. 进入这个文件夹后，下面咱们要在这个黑色的窗口里安装并初始化 VitePress。

7. 初始化项目：

npm init -y

8. 安装 VitePress、Vue 和侧边栏插件：

npm add -D vitepress vue vitepress-sidebar

9. 运行初始化向导（这条只需要跑一次）：

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
Add VitePress npm scripts?                     →  Yes

关于 TypeScript 那一问：我最早写这篇时建议新手选 No。现在改成推荐 Yes。原因很实际 —— 选 Yes 生成的是 config.mts，跟本文后面贴的所有代码、以及网上绝大多数 VitePress 教程都对得上；选 No 生成 config.mjs，抄代码时会多一层困惑。它并不要求你会 TypeScript，配置写法完全一样。

10. 启动本地预览：

npm run dev

终端会给出一个地址（通常是 http://localhost:5173）。把这个地址复制到浏览器打开，你就会看到一个清新、带侧边栏的个人网站原型了！

如果这一步报错 npm : 无法加载文件 ...\npm.ps1，因为在此系统上禁止运行脚本 —— 请看文末的 troubleshooting，两分钟能解决。

11. 在你的 my-blog 文件夹里，找到 .vitepress/config.mts 文件。

.vitepress 是隐藏文件夹。在文件资源管理器里，点顶部"查看" → 勾选"隐藏的项目"就能看到。或者直接用 VS Code 打开整个 my-blog 文件夹，什么都看得见。

12. 打开 config.mts，把内容替换成文末【我正在用的配置】那一段（记得改成你自己的名字和链接）。

13. 创建对应的文件。

配置好了路径，你需要在 my-blog 根目录下创建对应的文件夹和文件，网页才能显示内容：

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

回到浏览器刷新一下，你会发现侧边栏已经完全按照你的逻辑排好了！

如果没刷出来，大概率是路径问题，把 config.mts 和你的文件夹结构一起贴给 AI 让它对一下。

14. 如果需要图片：在 my-blog 根目录下创建一个文件夹，命名为 public（VitePress 专门存放静态资源的地方）。找一张图片（比如 test.jpg）丢进去。

在 Markdown 里引用时，路径写 /test.jpg 就行，不需要写 public：

![](/截图-1.png)

---

第二部分：推送到 GitHub

15. 下载并安装 Git for Windows，下载后一路点击"Next"安装即可。装完后在终端输入 git --version，看到版本号即成功。

16. ⚠️ 先建 .gitignore，再做任何 git add。这一步顺序错了会很麻烦。

在 my-blog 根目录新建一个文件，名字就叫 .gitignore（注意前面有个点，没有后缀），内容：

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

为什么必须先做：node_modules 是 npm 装进来的几万个第三方库文件，几百 MB。Vercel 部署时会根据 package.json 自己重装一遍，根本不需要你传上去。

而 .gitignore 只对还没被提交过的文件生效。一旦某个文件已经进了 git 的记录，之后再把它写进 .gitignore 也没用，它会一直跟着你。

我自己就是没注意这个顺序，node_modules 里 5341 个文件被一起提交了上去，几个月后才发现，清理的时候得用 git rm -r --cached node_modules 单独摘一次。你现在花 30 秒建这个文件，能省掉这件事。

顺带一提：如果你也用 Obsidian 管理这个文件夹，把 .obsidian/ 和 .trash/ 也加进去 —— 那是 Obsidian 的本地工作区状态和已删笔记，不该进仓库。

17. 在 GitHub 创建仓库 (Repository)，目的是给你的本地代码做一个中转站：

1. 登录你的 GitHub
2. 点击右上角的 + → New repository
3. 名字起为 my-blog
4. Public 或 Private 都可以 —— 选 Private 完全不影响 Vercel 部署，Vercel 走的是 GitHub App 授权，私有仓库照样能拉取构建，你的网站本身还是公开可访问的。如果你的笔记里有不想公开的草稿，直接选 Private。
5. 不要勾选 "Add a README file" / "Add .gitignore" / "Choose a license" 里的任何一项（会和你本地的文件冲突）
6. 点 Create repository

18. 回到 PowerShell，依次运行：

git init

git add .

git commit -m "first commit"

如果这里报错说需要身份信息，先跑这两条（复制粘贴，不要删掉双引号）：

git config --global user.email "你的邮箱@example.com"

git config --global user.name "你的名字"

然后重新 git commit。

19. 关联远程仓库并推送（记得把 你的用户名 换成真实的）：

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

git branch -M main

git push -u origin main

关于 main 和 master：早年 Git 默认分支叫 master，GitHub 从 2020 年起默认改成了 main。上面那条 git branch -M main 就是把本地分支统一改名成 main，这样和 GitHub 对得上。

如果你在别处看到 git push -u origin master 报错说分支不存在，就是这个原因。

Windows 第一次推送会弹出一个窗口让你登录 GitHub，点浏览器授权即可。

20. **记住这三个命令。**每当你本地的文件更改之后，运行这三个，Vercel 才会看到更新：

git add .

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

git push

引号里的中文是这次改动的说明，随便写，是给未来的你自己看的。

---

第三部分：部署到 Vercel

21. 绑定 Vercel（实现免费公网访问）：

1. 前往 Vercel 官网，用你的 GitHub 账号直接登录
2. 点击右上角 Add New → Project
3. 你会看到刚才创建的 my-blog 仓库，点击 Import
4. Vercel 通常会自动识别 VitePress。确保 Framework Preset 选的是 VitePress（或 Other），然后点击 Deploy

22. 如果构建失败，去项目 Settings → Build & Development Settings 手动指定：

• Install Command：npm install
• Build Command：node node_modules/vitepress/bin/vitepress.js build
• Output Directory：.vitepress/dist

为什么要绕这一下：直接写 vitepress build 时，Vercel 的 Linux 环境偶尔会因为可执行文件权限问题报 Permission Denied，找不到命令。绕开那个快捷方式、直接用 node 去调用它背后的那个 js 文件，就不看权限了。

23. 确认有没有部署成功的方法：

回到你的 Vercel Dashboard：

• 成功了：你会看到你的项目卡片上有一个 "Ready" 的绿色标签，并且有一个预览图（是你网站的样子）
• 正在跑：如果看到 "Building" 或蓝色进度条，说明它正在努力，等一两分钟
• 失败了：会显示红色的 "Error" 或 "Failed"。点进去看 Build Logs，把红色的报错原文复制出来贴给 AI，基本都能解

---

第四部分：绑定自己的域名

24. 在 Cloudflare 上购买域名（Cloudflare 是按成本价卖的，不加价，比大部分域名商便宜）。

25. 在 Vercel 里添加域名：项目 → Settings → Domains → 输入你的域名 → Add。

26. Vercel 会给你一张卡片，上面写着需要配置的 DNS 记录。

⚠️ 一定要照着 Vercel 页面上显示给你的那组值填，不要抄任何教程里写死的数字 —— 包括这一篇。

Vercel 现在会按项目和套餐分配不同的地址：老项目的 A 记录多半是 76.76.21.21，新建的项目可能拿到 216.198.79.1 或者别的；www 的 CNAME 也从过去统一的 cname.vercel-dns.com 变成了每个项目独有的一串（形如 d1d4fc829fe7bc7c.vercel-dns-017.com）。填了不属于你项目的值，验证会一直不通过，而且报错信息不会告诉你是这个原因。

去 Cloudflare 后台 → DNS → 添加两条：

类型	名称	内容
A	@	Vercel 卡片上显示的那个 IP
CNAME	www	Vercel 卡片上显示的那串

27. Cloudflare 特有的两个坑：

1. 必须去 SSL/TLS 菜单，把加密模式改为 Full（或 Full strict）。默认的 Flexible 会导致无限重定向，网站直接打不开。
2. 上面那两条记录右边的小云朵图标，先点成灰色（DNS only）。橙色代理开着的时候 Vercel 有时验证不过去。等域名验证通过、网站能打开了，再决定要不要开橙色。

---

第五部分（高阶）：和 Obsidian 联动

部署成功后，用 Obsidian 接管这个文件夹能大幅提高更新效率 —— 你就在一个笔记软件里写字，写完点一下就上线了。

28. 在 Obsidian 中"接管"你的博客：

1. 打开 Obsidian
2. 点击左下角的 "Open another vault"（打开另一个库）
3. 点击 "Open folder as vault"
4. 选择你的根目录：C:\Users\chuan\my-blog

现在，你在左侧能看到 logs、public、.vitepress 等所有文件夹。

29. 配置 Obsidian，让它像网页一样工作：

1. Files & Links（文件与链接）
   • Default location for new attachments → 改为 Same folder as current file（这样图片会存在笔记旁边，网页才能找到）
   • Use [[Wikilinks]] → 关闭它（重要！网页只认标准 Markdown 链接 [描述](路径)，不认双方括号 [[]]）
2. Editor（编辑器）
   • Default view mode → 设为 Live Preview，这样你写公式和结构笔记时会有即时预览
3. 安装社区插件 GitHobs，可以直接在 Obsidian 里完成推送，不用切回终端

⚠️ 用 Obsidian 之后记得检查 .gitignore 里有没有 .obsidian/ 和 .trash/（见第 16 步）。Obsidian 会在你的文件夹里生成工作区布局、插件配置和已删笔记的备份，这些都是本地状态，不该进仓库。

---

Troubleshooting

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

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

1. 点击 Windows 开始菜单，搜索 PowerShell
2. 右键点击 "Windows PowerShell"，选择 "以管理员身份运行"（这一步非常重要）
3. 输入以下命令并回车：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

4. 终端会询问你是否确认，输入 Y 然后回车
5. 关闭这个管理员窗口，回到你之前的普通 PowerShell 窗口（即 C:\Users\chuan\my-blog 那个路径），重新尝试刚才失败的命令

如果这次成功了，你会看到屏幕上弹出一串关于 package.json 的文本，这意味着你的"地基"已经打好了。

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

检查有没有 .vitepress/theme/index.ts 这个文件，并且里面 import 了你的 css。CSS 文件必须被这个入口文件引入才会生效 —— 这是新手最常见的"我明明写了样式却没反应"。

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

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

构建报错 dead link

VitePress 默认把死链当致命错误、直接中断构建。在 config.mts 里加 ignoreDeadLinks: true。

PowerShell 常用命令

命令	作用
ls	展示当前文件夹的内容
cd 路径	进入某个文件夹，比如 cd C:\Users\chuan\my-blog
cd ..	返回上一层文件夹
npm run dev	启动本地预览
npm run build	本地构建一次，提前发现会不会报错
git status	看看哪些文件改动了

---

我正在用的配置，供你参考

下面是 chuanbaozheng.com 实际在跑的文件。

.vitepress/config.mts

网站的最高指挥部。侧边栏长什么样、网站叫什么名字、顶部导航栏去哪里，都在这里配置。

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

export default defineConfig({
  // 1. 基础配置（默认 = 英文 root locale）
  title: "Chuanbao's Space",
  description: 'Protein design & wet-lab notes',
  ignoreDeadLinks: true,  // 无视死链，强制构建
  cleanUrls: true,        // 🌟 核心：启用简洁 URL，解决文件夹 index 路由 404 问题

  // 🌟 自定义域名必备：设置站点地图，让 Google 更好搜到你
  sitemap: {
    hostname: 'https://chuanbaozheng.com'
  },

  // 🌟 确保 base 为根目录，这样自定义域名的图片/样式才不会错位
  base: '/',

  appearance: false,   // 暗黑模式开关，见下方说明
  lastUpdated: true,

  // 🌟 中英双语：English 是 root（无前缀），中文在 /zh/ 下
  locales: {
    root: {
      label: 'English',
      lang: 'en-US',
    },
    zh: {
      label: '简体中文',
      lang: 'zh-CN',
      link: '/zh/',
      title: 'Chuanbao',
      description: '蛋白质设计与实验笔记',
      themeConfig: {
        nav: [
          { text: '首页', link: '/zh/' },
          { text: '研究', link: '/zh/research' },
          { text: '项目', link: '/zh/projects' },
          { text: '日志', link: '/logs/' },
          { text: '关于我', link: '/zh/about-me' },
          { text: '简历', link: '/zh/cv' },
        ],
        outline: { label: '本页目录', level: [2, 3] },
        lastUpdatedText: '最后更新时间',
        footer: {
          message: 'chuanbaozheng77@gmail.com',
          copyright: `Copyright © 2026-${new Date().getFullYear()} Chuanbao`,
        },
      },
    },
  },

  // 🌟 favicon + 社交分享元信息
  head: [
    ['link', { rel: 'icon', type: 'image/svg+xml', href: '/favicon.svg' }],
    ['meta', { name: 'theme-color', content: '#4f5fd6' }],
    ['meta', { property: 'og:type', content: 'website' }],
    ['meta', { property: 'og:title', content: "Chuanbao's Space" }],
    ['meta', { property: 'og:url', content: 'https://chuanbaozheng.com/' }],
    ['meta', { name: 'twitter:card', content: 'summary' }],
  ],

  themeConfig: {
    // 1. 顶部导航栏配置（英文 root）
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Research', link: '/research' },
      { text: 'Projects', link: '/projects' },
      { text: 'Notes', link: '/logs/' },
      { text: 'About', link: '/about-me' },
      { text: 'CV', link: '/cv' },
    ],

    // 2. 侧边栏
    //    /logs/    → 自动扫描生成
    //    /academy/ → 手写（顺序有讲究，不能按文件名排）
    sidebar: {
      // 🌟 注意这里的三个点。generateSidebar 带 resolvePath 时，返回的已经是
      //    { '/logs/': [...] } 这种带路径 key 的对象，所以要用 ... 展开进来，
      //    才能和下面手写的 '/academy/' 并存。
      //    如果你只有一个自动侧边栏、不需要手写第二个，直接写
      //    sidebar: generateSidebar([...]) 就行，不用套这层大括号。
      ...generateSidebar([
        {
          documentRootPath: '/',
          scanStartPath: 'logs',
          resolvePath: '/logs/',
          useTitleFromFileHeading: true,
          useFolderTitleFromIndexFile: true, // 文件夹里有 index.md，就用它的标题
          collapsed: true,
          hyphenToSpace: true,
          sortMenusByName: true
        }
      ]),

      '/academy/': [
        {
          text: 'Protein Design Journey',
          items: [
            { text: 'Dashboard', link: '/academy/' },
            { text: 'Knowledge Map', link: '/academy/map' },
            { text: 'Changelog', link: '/academy/changelog' },
          ],
        },
        {
          text: 'Learn',
          items: [
            { text: 'Curriculum', link: '/academy/curriculum/' },
            { text: 'Knowledge Base', link: '/academy/knowledge/' },
            { text: 'Paper Library', link: '/academy/papers/' },
          ],
        },
        {
          text: 'Research',
          items: [
            { text: 'Research Lab', link: '/academy/lab/' },
            { text: 'Timeline', link: '/academy/timeline' },
            { text: 'Unknown Unknown', link: '/academy/unknowns' },
          ],
        },
      ],
    },

    // 3. 文章大纲与目录
    outline: { label: 'On this page', level: [2, 3] },
    aside: true,

    // 4. 社交链接
    socialLinks: [
      { icon: 'github', link: 'https://github.com/superaseraser' },
      { icon: 'linkedin', link: 'https://www.linkedin.com/in/chuanbao-zheng-05a081202/' }
    ],

    // 5. 页脚与更新时间
    lastUpdatedText: 'Last updated',
    footer: {
      message: 'chuanbaozheng77@gmail.com',
      copyright: `Copyright © 2026-${new Date().getFullYear()} Chuanbao`
    }
  }
})

两条经验，都是踩出来的：

appearance: false —— 我一开始是开着暗黑模式的（true）。后来自定义 CSS 越写越多，亮色暗色两套配色要各调一遍，每加一个组件就得检查两遍，维护成本直接翻倍，最后干脆关掉了。如果你就用默认主题不怎么改样式，大胆开 true，VitePress 自带的暗色做得很好看。 是自定义程度决定要不要关，不是暗色本身不好。

双语的坑 —— VitePress 假设两种语言的路径完全对称。我的 logs/ 只有中文、没有英文镜像，结果在 logs 页面点语言切换按钮会直接 404，最后是写了一小段路由拦截代码才修好的。如果你要做双语，要么两边页面都建齐，要么就接受某些板块只有一种语言、并且提前想好切换器怎么处理。

.vitepress/theme/custom.css

负责"好看"。控制颜色、字体大小、布局微调。没有它，网站就是素颜。

/* =========================================
   1. 布局修正：导航链接靠左，社交/搜索靠右
   ========================================= */

.VPNavBar .content-body {
  display: flex !important;
  justify-content: flex-start !important;
}

/* 核心：将菜单推向左侧，把剩余空间留给右侧 */
.VPNavBarMenu {
  flex-grow: 0 !important;
  margin-right: auto !important;  /* 🌟 关键：推开右侧所有内容 */
  margin-left: 32px !important;
}

.VPNavBarSearch,
.VPNavBarAppearance,
.VPNavBarSocialLinks {
  flex-grow: 0 !important;
  margin-left: 12px !important;
}

/* 移动端：在手机上保持汉堡菜单在右边 */
@media (max-width: 959px) {
  .VPNavBar .content-body {
    justify-content: space-between !important;
  }
}

/* =========================================
   2. 首页 Hero：默认字号太吵，缩小
   ========================================= */

.VPHero .name {
  font-size: 38px !important;
  line-height: 44px !important;
}

.VPHero .text {
  font-size: 26px !important;
  line-height: 32px !important;
}

.VPHero .tagline {
  font-size: 16px !important;
  color: var(--vp-c-text-2) !important;
}

.vitepress/theme/index.ts

主题的入口文件。用来引入上面的 custom.css，把装修方案正式应用到房子上。漏了这个文件，你的 CSS 一行都不会生效。

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

export default {
  extends: DefaultTheme,
}

index.md

你的首页内容。打开 chuanbaozheng.com 第一眼看到的文字和按钮，都写在这里。

⚠️ 注意最上面和最下面各有一行 ---，两行都不能少。中间那部分叫 frontmatter，是给 VitePress 看的配置，少了开头那行整个页面会渲染成一坨纯文本。

---
layout: home
hero:
  name: "Chuanbao's Space"
  text: "Bio-Design & Digital Life"
  tagline: 记录每一个成功搭建环境的小瞬间
  image:
    src: /test-cat.png
    alt: 我的测试猫
  actions:
    - theme: brand
      text: About me
      link: /about-me
    - theme: alt
      text: 开始阅读
      link: /logs/

features:
  - icon: 🧬
    title: 蛋白质设计
    details: 记录 RFdiffusion, AlphaFold 和结构生物学的点点滴滴。
    link: /logs/learning/protein-design/AlphaFold2
  - icon: 🔬
    title: 实验技能
    details: 湿实验操作规范与避坑指南。
    link: /logs/learning/Basic-biology/lab-skills/lab-skill-list
  - icon: 📚
    title: 读书笔记
    details: 把看过的书沉淀为成长的养料。
    link: /logs/learning/books-and-other/Books/books
---

features 里的 link 必须指向你真实存在的文件路径，否则点进去是 404。写完自己都点一遍。

package.json

记录了网站需要哪些"零件"（插件）以及怎么启动、怎么构建的指令。

{
  "name": "my-blog",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "vitepress dev",
    "build": "node node_modules/vitepress/bin/vitepress.js build",
    "preview": "vitepress preview"
  },
  "dependencies": {
    "vitepress": "latest",
    "vitepress-sidebar": "^1.33.1",
    "vue": "latest"
  }
}

.gitignore

别忘了这个文件（见第 16 步）。

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

---

另一个版本供你参考：精简版-零基础-如何8个小时内拥有自己的个人网站

💡 写给读者的话

"你一定可以的！"