VitePress 学习指南

主题

电商文档站搭建 ​

本教程将教你如何使用 VitePress 搭建一个专业的电商平台文档站，包含商品文档、API 文档、开发者指南和帮助中心。

项目概述 ​

功能特性 ​

功能说明
商品文档中心商品分类、搜索、详情页
API 文档RESTful API 参考、SDK 示例
帮助中心FAQ、工单入口、使用教程
开发者指南接入指南、Webhook、回调通知
多版本管理API v1/v2 版本切换
国际化中英文切换

站点结构 ​

docs/
├── .vitepress/
│   ├── config.mts          # 配置文件
│   └── theme/
│       ├── index.ts        # 主题入口
│       ├── components/     # 自定义组件
│       │   ├── ApiEndpoint.vue    # API 端点组件
│       │   ├── SdkExample.vue     # SDK 代码示例
│       │   ├── CallbackFlow.vue   # 回调流程图
│       │   └── HelpSearch.vue     # 帮助搜索
│       └── composables/
│           └── useApiSpec.ts       # API 数据加载
├── index.md                # 首页
├── products/               # 商品文档
│   ├── index.md
│   ├── payment.md          # 支付产品
│   └── logistics.md        # 物流产品
├── api/                    # API 文档
│   ├── index.md
│   ├── v2/
│   │   ├── payment.md      # 支付 API
│   │   ├── order.md        # 订单 API
│   │   └── refund.md       # 退款 API
│   └── v1/                 # 旧版 API
├── guide/                  # 开发者指南
│   ├── quickstart.md       # 快速接入
│   ├── webhook.md          # Webhook 配置
│   └── callback.md         # 回调通知
└── help/                   # 帮助中心
    ├── index.md
    ├── faq.md
    └── contact.md          # 联系支持

配置文件 ​

多版本 API 侧边栏 ​

ts
// docs/.vitepress/config.mts
import { defineConfig } from 'vitepress'

export default defineConfig({
  title: '电商平台文档',
  description: '完整的电商 API 文档和开发者指南',

  head: [
    ['meta', { name: 'keywords', content: '电商API,支付API,物流API,开发者文档' }]
  ],

  themeConfig: {
    nav: [
      { text: '首页', link: '/' },
      { text: '商品文档', link: '/products/' },
      { text: 'API 文档', link: '/api/v2/' },
      { text: '开发者指南', link: '/guide/quickstart' },
      { text: '帮助中心', link: '/help/' }
    ],

    sidebar: {
      '/products/': [
        {
          text: '产品文档',
          items: [
            { text: '产品概览', link: '/products/' },
            { text: '支付产品', link: '/products/payment' },
            { text: '物流产品', link: '/products/logistics' }
          ]
        }
      ],

      '/api/v2/': [
        {
          text: 'API v2（推荐）',
          items: [
            { text: 'API 概览', link: '/api/v2/' },
            {
              text: '支付接口',
              items: [
                { text: '统一下单', link: '/api/v2/payment' },
                { text: '订单查询', link: '/api/v2/order' },
                { text: '申请退款', link: '/api/v2/refund' }
              ]
            }
          ]
        },
        {
          text: '旧版 API',
          items: [
            { text: 'API v1（已弃用）', link: '/api/v1/' }
          ]
        }
      ],

      '/guide/': [
        {
          text: '开发者指南',
          items: [
            { text: '快速接入', link: '/guide/quickstart' },
            { text: 'Webhook 配置', link: '/guide/webhook' },
            { text: '回调通知', link: '/guide/callback' }
          ]
        }
      ],

      '/help/': [
        {
          text: '帮助中心',
          items: [
            { text: '常见问题', link: '/help/faq' },
            { text: '联系支持', link: '/help/contact' }
          ]
        }
      ]
    }
  }
})

自定义组件 ​

API 端点组件 ​

vue
<!-- docs/.vitepress/components/ApiEndpoint.vue -->
<script setup lang="ts">
interface Props {
  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'
  path: string
  description?: string
  deprecated?: boolean
}

const props = withDefaults(defineProps<Props>(), {
  description: '',
  deprecated: false
})

const methodColors: Record<string, string> = {
  GET: 'get',
  POST: 'post',
  PUT: 'put',
  DELETE: 'delete',
  PATCH: 'patch'
}
</script>

<template>
  <div class="api-endpoint" :class="{ deprecated }">
    <div class="endpoint-header">
      <span class="method" :class="methodColors[method]">{{ method }}</span>
      <code class="path">{{ path }}</code>
      <span v-if="deprecated" class="badge deprecated-badge">已弃用</span>
    </div>
    <p v-if="description" class="endpoint-desc">{{ description }}</p>
    <slot />
  </div>
</template>

<style scoped>
.api-endpoint {
  border: 1px solid var(--vp-c-divider);
  border-radius: 8px;
  padding: 16px;
  margin: 16px 0;
}

.api-endpoint.deprecated {
  opacity: 0.7;
  border-style: dashed;
}

.endpoint-header {
  display: flex;
  align-items: center;
  gap: 12px;
  margin-bottom: 8px;
}

.method {
  font-size: 12px;
  font-weight: 700;
  padding: 2px 8px;
  border-radius: 4px;
  text-transform: uppercase;
  color: white;
}

.method.get { background: var(--vp-c-green-1); }
.method.post { background: var(--vp-c-brand-1); }
.method.put { background: var(--vp-c-warning-1); }
.method.delete { background: var(--vp-c-danger-1); }
.method.patch { background: #8b5cf6; }

.path {
  font-family: var(--vp-font-family-mono);
  font-size: 14px;
}

.badge.deprecated-badge {
  font-size: 11px;
  padding: 1px 6px;
  border-radius: 4px;
  background: var(--vp-c-warning-soft);
  color: var(--vp-c-warning-1);
}
</style>

SDK 代码示例组件 ​

vue
<!-- docs/.vitepress/components/SdkExample.vue -->
<script setup lang="ts">
interface Props {
  language: string
}

defineProps<Props>()
</script>

<template>
  <div class="sdk-example">
    <slot />
  </div>
</template>

首页配置 ​

markdown
---
layout: home

hero:
  name: "电商文档"
  text: "开发者平台"
  tagline: 快速接入支付、物流等电商核心能力
  actions:
    - theme: brand
      text: 快速接入
      link: /guide/quickstart
    - theme: alt
      text: API 文档
      link: /api/v2/

features:
  - title: 支付 API
    details: 覆盖微信支付、支付宝、银联等主流支付方式
    link: /api/v2/payment
    icon: 💳
  - title: 物流 API
    details: 对接主流快递公司，实现自动下单和轨迹追踪
    link: /products/logistics
    icon: 📦
  - title: Webhook
    details: 实时接收订单状态变更通知，确保业务同步
    link: /guide/webhook
    icon: 🔔
  - title: 沙箱环境
    details: 提供完整的模拟环境，零成本调试接口
    link: /guide/quickstart
    icon: 🧪
---

API 文档示例 ​

统一下单接口 ​

markdown
---
title: 统一下单 API
---

# 统一下单

创建一笔支付订单，获取支付凭证。

<ApiEndpoint
  method="POST"
  path="/api/v2/payments/create"
  description="创建支付订单"
/>

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| out_trade_no | string | 是 | 商户订单号（最长 32 位） |
| total_fee | integer | 是 | 订单金额，单位：分 |
| subject | string | 是 | 商品标题 |
| body | string | 否 | 商品描述 |
| notify_url | string | 是 | 回调通知地址 |
| pay_type | string | 是 | 支付方式：`wechat` / `alipay` / `unionpay` |
| expire_time | string | 否 | 过期时间，默认 30 分钟 |

### 请求示例

\`\`\`bash
curl -X POST https://api.example.com/api/v2/payments/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "out_trade_no": "ORDER20260331001",
    "total_fee": 100,
    "subject": "测试商品",
    "notify_url": "https://your-domain.com/callback",
    "pay_type": "wechat"
  }'
\`\`\`

### 响应参数

| 参数 | 类型 | 说明 |
|------|------|------|
| code | integer | 状态码，0 表示成功 |
| data.pay_url | string | 支付链接（H5/PC） |
| data.pay_params | object | JSAPI 支付参数（小程序） |
| data.trade_no | string | 平台订单号 |

### 响应示例

\`\`\`json
{
  "code": 0,
  "data": {
    "trade_no": "TP2026033112345",
    "pay_url": "https://pay.example.com/checkout?token=xxx",
    "pay_params": {
      "appId": "wx1234567890",
      "timeStamp": "1711852800",
      "nonceStr": "abc123",
      "package": "prepay_id=wx20170101",
      "signType": "RSA",
      "paySign": "xxx"
    }
  }
}
\`\`\`

::: warning 注意事项
- `out_trade_no` 必须全局唯一，重复提交将返回错误
- `total_fee` 最小值为 1（即 0.01 元）
- 生产环境请使用 HTTPS 协议
:::

帮助中心示例 ​

FAQ 页面 ​

markdown
---
title: 常见问题
---

# 常见问题

## 支付相关

### Q: 支持哪些支付方式？

A: 目前支持以下支付方式：

| 支付方式 | 场景 | 说明 |
|---------|------|------|
| 微信支付 | 小程序、H5、PC 扫码 | 最常用的支付方式 |
| 支付宝 | H5、PC | 覆盖支付宝用户 |
| 银联支付 | PC、H5 | 适合大额支付场景 |

### Q: 退款多久到账？

A: 不同支付方式的退款到账时间：

| 支付方式 | 到账时间 |
|---------|---------|
| 微信支付 | 1-3 个工作日 |
| 支付宝 | 即时到 24 小时 |
| 银联支付 | 3-5 个工作日 |

### Q: 如何处理支付失败？

1. 检查 API Key 是否正确
2. 确认订单金额是否符合限制
3. 查看 [错误码文档](/api/v2/#error-codes) 定位问题
4. 如仍无法解决，请[联系技术支持](/help/contact)

## 接入相关

### Q: 沙箱环境如何使用？

1. 登录控制台创建沙箱应用
2. 获取沙箱环境的 API Key
3. 使用沙箱地址 `https://sandbox-api.example.com`
4. 测试通过后切换为生产环境

::: tip 提示
沙箱环境支持模拟各种支付场景（成功、失败、超时等）。
:::

进阶挑战 ​

挑战难度说明
实现 API Playground⭐⭐⭐⭐嵌入在线 API 测试工具
添加 Webhook 调试面板⭐⭐⭐可视化查看 Webhook 推送记录
多语言 API 文档⭐⭐⭐⭐中英文 API 文档切换
生成 SDK 文档⭐⭐⭐⭐⭐从 OpenAPI 规范自动生成 SDK 文档

下一步 ​

贡献者

加载中...

想要成为贡献者？

在 CNB 上参与贡献

Copyright © 2016 - 2026 VitePress 学习指南