Appearance

🚀 百闻AI Coworker 部署说明 ​

Base 路径自动适配 ​

本项目的 VitePress 配置已经兼容 Vercel、自定义域名 与 GitHub Pages 的不同部署路径，并支持通过环境变量覆盖站点域名。

自动适配逻辑 ​

javascript
// docs/.vitepress/config.mjs
const isVercel = process.env.VERCEL === '1' || !!process.env.VERCEL_URL
const base = process.env.BASE || (isVercel ? '/' : '/easy-vibe/')
const siteUrl = process.env.SITE_URL || process.env.VERCEL_PROJECT_PRODUCTION_URL

部署环境对比 ​

平台Base 路径站点域名建议示例 URL
Vercel / 自定义域名/设置 SITE_URL=https://your-domain.comhttps://your-domain.com/zh-cn/stage-0/...
GitHub Pages/easy-vibe/设置 SITE_URL=https://your-org.github.io/easy-vibehttps://your-org.github.io/easy-vibe/zh-cn/stage-0/...
本地开发/easy-vibe/使用默认本地地址http://localhost:5175/easy-vibe/zh-cn/stage-0/...
本地预览/easy-vibe/使用默认本地地址http://localhost:4175/easy-vibe/zh-cn/stage-0/...

首页动态链接 ​

首页使用 VitePress 的 useData() API 来动态获取 base 路径：

vue
<script setup>
import { useData } from 'vitepress'

const { site } = useData()
const base = site.value.base
</script>

<template>
  <a :href="base + 'cn/stage-0/0.1-learning-map/'">
    <!-- 链接会自动适配部署环境 -->
  </a>
</template>

优点：

  • ✅ 无需硬编码 fallback 值
  • ✅ 自动适配 Vercel 和 GitHub Pages
  • ✅ 构建时和运行时都正确

部署步骤 ​

推荐环境变量 ​

  • SITE_URL：站点正式外部访问域名，用于 canonical、OG、sitemap、robots 等 SEO 输出
  • BASE：仅在确实需要子路径部署时设置，例如 /easy-vibe/

Vercel 部署 ​

  1. 推送代码到 GitHub
  2. Vercel 会自动检测 vercel.json 配置
  3. 设置 SITE_URL=https://your-domain.com 或你的正式预览域名
  4. 自动构建并部署
  5. 访问你的正式域名

GitHub Pages 部署 ​

  1. 配置 GitHub Pages 设置：

    • Source: gh-pages 分支
    • 或使用 GitHub Actions 从 main 分支部署

  2. 构建命令：

    bash
    npm run build

  3. 建议额外设置 SITE_URL=https://your-org.github.io/easy-vibe

  4. 访问你的 GitHub Pages 地址

验证部署 ​

部署后检查以下链接是否正常：

  • [ ] 首页能正常访问
  • [ ] 导航栏链接能正确跳转
  • [ ] 首页卡片"查看详情"链接正确
  • [ ] 语言切换功能正常
  • [ ] 图片资源能正常加载

常见问题 ​

Q: Vercel 部署后链接变成 /easy-vibe/zh-cn/... 导致 404 ​

原因：Vercel 环境变量未正确设置

解决：

  1. 检查是否误设了 BASE=/easy-vibe/
  2. 确认 SITE_URL 指向正式域名
  3. 重新部署

Q: GitHub Pages 部署后所有链接 404 ​

原因：缺少 /easy-vibe/ base 路径

解决：

  1. 检查 docs/.vitepress/config.mjs 中的 base 配置
  2. 确保 GitHub Pages 环境下 BASE=/easy-vibe/ 或使用默认值
  3. 重新构建并部署

Q: 本地预览链接缺少 /easy-vibe/ 前缀 ​

原因：使用了错误的预览命令

解决：

bash
# 错误
npm run preview  # 默认端口 4175，但路径可能不对

# 正确
npm run build
npm run preview  # 访问 http://localhost:4175/easy-vibe/