前言

大家好，我是林大哥。

之前发了一篇《 我用24小时搭建了一个电商的线报网站》，不少读者问我：我是怎么学会用这些工具的？

线报网站地址放到这里了http://www.taobaoketool.com，大家可以去看看效果！！！

其实答案很简单：不是学会的，是 AI 帮忙做的。

今天我要写的，是另外一件事——我是如何用 OpenClaw搭建了 www.moltcn.com 这个 OpenClaw 中文社区文档网站的。

整个过程大概花了几天时间，中间踩了不少坑。这篇文章不吹不黑，把我遇到的问题和解决方法都写出来，方便后续想搭建类似网站的朋友参考。

---

一、为什么我要自己搭建网站

1.1 官方文档不够用

OpenClaw 是个开源项目，官方文档是英文的。虽然功能很强大，但对于中文用户来说，学习成本还是比较高的。

我之前写了些中文教程文章，放在 GitHub 上。但问题来了：

• 访问速度慢（GitHub 在国内经常抽风）
• 样式丑（GitHub Pages 默认主题）
• 不好搜索
• 没法做 SEO

1.2 市面方案对比

方案	优点	缺点
WordPress	功能全	太重，需要维护
Notion	简单	国内访问慢，SEO 差
Docsify	轻量	主题少
VitePress	快、主题好、Vue 支持	需要一点配置

最后选了 VitePress，原因很简单：快、好看、文档类网站首选。

---

二、搭建过程：我是怎么做的

2.1 第一步：创建项目

# 创建项目目录
mkdir clawd-docs
cd clawd-docs

# 初始化 npm
npm init -y

# 安装 VitePress
npm install -D vitepress vue

# 创建一个基础文档
mkdir docs
echo '# Hello' > docs/index.md

难度：⭐（和装一个 npm 包差不多）

2.2 第二步：配置 VitePress

这是最核心的一步。VitePress 的配置主要在 .vitepress/config.js 里：

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'OpenClaw中文社区',
  description: 'OpenClaw开源AI智能体助手文档',
  
  themeConfig: {
    // 导航栏
    nav: [
      { text: '首页', link: '/' },
      { text: '快速开始', link: '/start/getting-started' },
      { text: '安装', link: '/install/' },
    ],
    
    // 侧边栏
    sidebar: [
      {
        text: '快速开始',
        items: [
          { text: '入门指南', link: '/start/getting-started' },
          { text: '安装向导', link: '/start/wizard' },
        ]
      }
    ],
    
    // 搜索
    search: {
      provider: 'local'
    }
  }
})

难度：⭐⭐（看文档就能懂）

2.3 第三步：运行预览

# 本地开发
npm run docs:dev

# 访问 http://localhost:5173

到这一步，一个基础的文档网站就搭好了。

---

三、我踩过的坑：每一个都让我头疼

坑1：Node.js 版本不对，VitePress 装不上

问题描述：
刚开始装 VitePress 的时候，一直报错。大概是这样的错误：

Error: The engine "node" is incompatible with this module

原因：
VitePress 要求 Node.js >= 18，但我本机用的是 Node.js 16。

解决方法：

# 检查当前版本
node --version

# 如果版本不对，用 nvm 切换
nvm install 18
nvm use 18

教训：很多前端工具对 Node.js 版本有要求，动手之前先查清楚。

---

坑2：本地搜索不工作

问题描述：
配置好了搜索，但输入关键词后一直转圈，没有任何结果。

原因：
VitePress 的本地搜索需要额外的依赖，而且配置有讲究。

解决方法：

# 确保安装了 minisearch
npm install -D vitepress-theme-demoblock

然后在配置里明确指定：

search: {
  provider: 'local',
  options: {
    miniSearch: {
      options: {
        fuzzy: 0.2,
        prefix: true
      }
    }
  }
}

教训：VitePress 的功能看着简单，但细节很多，官方文档要仔细看。

---

坑3：百度统计代码放哪？

问题描述：
我想加百度统计，但不知道在哪加。

解决方法：
在 VitePress 配置的 head 字段里加：

head: [
  ['script', {}, `
    var _hmt = _hmt || [];
    (function() {
      var hm = document.createElement("script");
      hm.src = "https://hm.baidu.com/hm.js?你的ID";
      var s = document.getElementsByTagName("script")[0];
      s.parentNode.insertBefore(hm, s);
    })();
  `]
]

教训：VitePress 的 head 配置几乎可以加任何第三方代码，百度统计、Google Analytics、AdSense 都可以这么加。

---

坑4：微信客服悬浮按钮

问题描述：
很多国内文档网站右下角有个微信客服按钮，我也想加一个。

解决方法：
VitePress 支持自定义主题，可以在 .vitepress/theme/index.js 里注册全局组件：

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

export default {
  ...DefaultTheme,
  enhanceApp({ app }) {
    // 注册全局组件
  }
}

然后写一个简单的 CSS 悬浮按钮：

.wechat-float {
  position: fixed;
  right: 20px;
  bottom: 20px;
  width: 50px;
  height: 50px;
  background: #07c160;
  border-radius: 50%;
  cursor: pointer;
  z-index: 9999;
}

教训：VitePress 基于 Vue 3，会 Vue 的话可以随便定制。

---

坑5：部署到 Vercel 一直失败

问题描述：
本地 npm run docs:dev 跑得好好的，一部署到 Vercel 就报错。

原因：
Vercel 默认不知道你要构建什么。VitePress 的构建命令是 vitepress build，不是默认的 npm run build。

解决方法：
在项目根目录创建 vercel.json：

{
  "buildCommand": "npm run docs:build",
  "outputDirectory": "docs/.vitepress/dist"
}

或者在 Vercel 后台设置：

• Build Command: npm run docs:build
• Output Directory: docs/.vitepress/dist

教训：部署平台不是万能的，有时候需要告诉它怎么构建。

---

坑6：域名解析问题

问题描述：
买了一个域名 moltcn.com，怎么都解析不到 Vercel。

原因：
Vercel 分配的是 *.vercel.app 域名，需要在域名提供商那里添加 CNAME 记录指向它。

解决方法：

1. 在 Vercel 后台 → Settings → Domains 添加你的域名
2. Vercel 会给你一个域名（如 clawd-docs.vercel.app）
3. 去域名服务商后台添加 DNS 记录：
   • 类型：CNAME
   • 主机记录：www（或 @）
   • 记录值：cname.vercel-dns.com（看 Vercel 给的具体地址）

教训：国内域名解析有时候需要等几分钟到几十分钟才生效，别急着改来改去。

---

坑7：SSL 证书一直不生效

问题描述：
域名解析好了，但 HTTPS 一直显示不安全。

原因：
Vercel 会自动申请 SSL 证书，但需要等待。

解决方法：
等。通常几分钟后自动生效。如果超过 10 分钟还不行，去 Vercel 后手动触发：

Settings → Domains → 点击域名 → 点击 “Renew Now”

教训：SSL 证书申请需要时间，别刚解析完就着急。

---

四、最终效果

经过几天的折腾，网站终于上线了：

• 网址：https://www.moltcn.com
• 主题：珊瑚红品牌色，暗黑模式
• 功能：
  • 本地搜索（支持中文）
  • 百度统计
  • 微信客服悬浮按钮
  • 响应式布局（手机也能看）
  • SEO 优化

---

五、总结：我的几点感悟

1. AI 工具真的能帮忙

从 0 到 1 搭这个网站，大部分工作是我和 AI 一起完成的。我负责提需求，AI 负责写代码。

遇到报错，我只需要把错误信息发给 AI，它就能帮我分析原因、提供解决方案。

2. 踩坑是必经之路

看完文档和实际动手是两回事。很多问题不亲自踩一遍，永远不知道。

3. 把问题记录下来

这是我这篇文章的初衷也是建议：每次遇到问题，一定要记录下来。时间久了，这就是你最宝贵的经验。

---

联系我

• 卫星：andyjackson（备注"OpenClaw"）
• 社区：OpenClaw 中文社区，欢迎加入一起交流