部署指南
本文档覆盖如何在本地运行、构建和部署文档网站。
前置要求
Node.js 安装
rspress需要Node.js 18+。
# 检查Node.js版本
node --version
# 应该显示 v18.0.0 或更高
# 如果没有安装，使用nvm安装
brew install nvm
nvm install 18
nvm use 18
项目依赖安装
cd /Users/zhangruobin/Episodes/Areas/interview-prepare
# 安装依赖（首次）
npm install
# 或使用pnpm（更快）
pnpm install
# 或使用yarn
yarn install
本地开发
启动开发服务器
npm run dev
# 输出：
# Server running at http://localhost:5173
打开浏览器访问 http://localhost:5173
开发服务器功能
- 🔄 热加载 - 修改markdown自动刷新
- 🔍 即时搜索 - 全文搜索所有文档
- 📱 响应式 - 自动适配手机、平板、桌面
- 🌙 暗黑模式 - 自动检测系统主题
构建和预览
生成静态网站
npm run build
# 输出：
# Build successful! Output directory: ./dist
本地预览构建结果
npm run preview
# 输出：
# Preview server running at http://localhost:4173
部署到GitHub Pages
方案1：使用GitHub Actions（推荐）
步骤1：创建GitHub仓库
cd /Users/zhangruobin/Episodes/Areas/interview-prepare
# 初始化git
git init
# 添加remote（替换YOUR_USERNAME和YOUR_REPO）
git remote add origin https://github.com/YOUR_USERNAME/go-agent-learn.git
git branch -M main
步骤2：创建GitHub Actions工作流
mkdir -p .github/workflows
创建文件 .github/workflows/deploy.yml：
name: Deploy to GitHub Pages
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: 18
- name: Install dependencies
run: npm install
- name: Build
run: npm run build
- name: Deploy to GitHub Pages
if: github.ref == 'refs/heads/main'
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./dist
cname: your-domain.com # 如果有自定义域名，替换这里
步骤3：推送代码
git add .
git commit -m "Init: 30天Go Agent Infrastructure学习计划"
git push -u origin main
步骤4：启用GitHub Pages
在GitHub仓库设置中：
- Settings → Pages
- Source: Deploy from a branch
- Branch: gh-pages / root
- Save
等待部署完成（通常1-2分钟）
访问：https://YOUR_USERNAME.github.io/go-agent-learn
方案2：使用Vercel（更简单）
Vercel 是最推荐的方案，因为：
- ✅ 自动构建和部署
- ✅ 支持自定义域名
- ✅ CDN加速全球访问
- ✅ 免费额度充足
步骤1：推送到GitHub
按照上面的"推送代码"步骤完成。
步骤2：连接Vercel
- 访问 vercel.com
- Sign up with GitHub
- Import project
- 选择
go-agent-learn 仓库
- Framework: Other
- Build Command:
npm run build
- Output Directory:
dist
- 点击Deploy
完成！ Vercel会自动部署，并给你一个 *.vercel.app 的URL。
步骤3（可选）：绑定自定义域名
在Vercel项目设置中：
- Domains → Add
- 输入你的域名（例如
learn-go-agent.yourdomain.com）
- 按照DNS配置指引完成
方案3：自托管（Docker）
如果你有自己的服务器：
Dockerfile
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
构建和运行
# 构建镜像
docker build -t go-agent-learn:latest .
# 运行容器
docker run -d -p 80:80 --name go-agent-learn go-agent-learn:latest
# 访问
# http://localhost
使用Docker Compose
version: '3.8'
services:
docs:
build: .
ports:
- "80:80"
restart: always
运行：
更新文档后的部署
本地工作流
# 1. 修改markdown文件
vim weekplan/week1_day1.md
# 2. 本地预览
npm run dev
# 访问 http://localhost:5173 检查效果
# 3. 提交代码
git add weekplan/week1_day1.md
git commit -m "Update: Day 1 教学材料"
git push
# GitHub Actions / Vercel 会自动部署
CI/CD流程
推送到main分支
↓
GitHub Actions / Vercel触发
↓
npm install & npm run build
↓
生成dist/文件夹
↓
自动部署到网站
↓
https://yoursite.com 更新完成
常见问题
Q: 本地运行 npm run dev 失败
检查清单：
# 1. Node.js版本
node --version # 应该≥v18.0.0
# 2. 依赖是否装好
npm list rspress
# 3. 清理缓存重新安装
rm -rf node_modules package-lock.json
npm install
Q: 构建后文件很大
rspress构建会生成2-5MB的静态文件，这是正常的。
Q: 部署后搜索不工作
搜索功能需要JavaScript启用。检查：
- 浏览器是否禁用了JavaScript
- rspress构建是否成功（检查dist/目录）
Q: 想要自定义域名
GitHub Pages：
在repo → Settings → Pages → Custom domain 输入域名，然后配置DNS CNAME记录。
Vercel：
在项目设置 → Domains 添加自定义域名。
Q: 想更改网站标题/Logo
编辑 rspress.config.ts：
export default defineConfig({
title: '你的新标题',
logo: {
light: '/你的logo.svg',
dark: '/你的logo-dark.svg',
},
// ...
});
修改后重新 npm run build 和部署。
故障排查
网站访问慢
- 使用Vercel CDN加速
- 检查图片是否过大
- 考虑启用gzip压缩
GitHub Pages 404
- 检查Settings → Pages中的branch是否正确
- 确认gh-pages分支已创建
- 清浏览器缓存重试
本地和线上显示不一致
# 清理缓存
rm -rf dist/ node_modules/
# 重新安装和构建
npm install
npm run build
# 本地预览
npm run preview
下一步
有问题？ 查看 常见问题 或提交Issue。