docs: stage-1 i18n coverage + news
This commit is contained in:
sanbuphy
+61
-85
@@ -1,29 +1,34 @@
|
||||
# 🚀 部署说明
|
||||
# Deployment Notes
|
||||
|
||||
## Base 路径自动适配
|
||||
## Base Path Auto-Adaptation
|
||||
|
||||
本项目的 VitePress 配置已经正确处理了 **Vercel** 和 **GitHub Pages** 两种部署环境的不同 base 路径。
|
||||
This project is a VitePress site that can be deployed to both **Vercel** and **GitHub Pages**. The main difference is the `base` path:
|
||||
|
||||
### 自动适配逻辑
|
||||
- Vercel: typically `/`
|
||||
- GitHub Pages: typically `/easy-vibe/`
|
||||
|
||||
```javascript
|
||||
The VitePress config handles this automatically:
|
||||
|
||||
```js
|
||||
// docs/.vitepress/config.mjs
|
||||
const isVercel = process.env.VERCEL === '1'
|
||||
const base = isVercel ? '/' : '/easy-vibe/'
|
||||
```
|
||||
|
||||
### 部署环境对比
|
||||
## Environment Comparison
|
||||
|
||||
| 平台 | Base 路径 | 示例 URL |
|
||||
| ---------------- | ------------- | ----------------------------------------------------------- |
|
||||
| **Vercel** | `/` | `https://your-project.vercel.app/cn/stage-1/...` |
|
||||
| **GitHub Pages** | `/easy-vibe/` | `https://datawhalechina.github.io/easy-vibe/cn/stage-1/...` |
|
||||
| **本地开发** | `/easy-vibe/` | `http://localhost:5173/easy-vibe/cn/stage-1/...` |
|
||||
| **本地预览** | `/easy-vibe/` | `http://localhost:4173/easy-vibe/cn/stage-1/...` |
|
||||
| Platform | Base | Example URL |
|
||||
| --- | --- | --- |
|
||||
| Vercel | `/` | `https://your-project.vercel.app/en/stage-1/...` |
|
||||
| GitHub Pages | `/easy-vibe/` | `https://datawhalechina.github.io/easy-vibe/en/stage-1/...` |
|
||||
| Local dev | `/easy-vibe/` | `http://localhost:5173/easy-vibe/en/stage-1/...` |
|
||||
| Local preview | `/easy-vibe/` | `http://localhost:4173/easy-vibe/en/stage-1/...` |
|
||||
|
||||
### 首页动态链接
|
||||
## Home Redirect And Dynamic Links
|
||||
|
||||
首页使用 VitePress 的 `useData()` API 来动态获取 base 路径：
|
||||
The home page uses VitePress `withBase()` and `useData()` to avoid hardcoding the base path.
|
||||
|
||||
Example:
|
||||
|
||||
```vue
|
||||
<script setup>
|
||||
@@ -34,86 +39,57 @@ const base = site.value.base
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<a :href="base + 'cn/stage-1/learning-map/'">
|
||||
<!-- 链接会自动适配部署环境 -->
|
||||
</a>
|
||||
<a :href="base + 'en/stage-1/learning-map/'">Go</a>
|
||||
</template>
|
||||
```
|
||||
|
||||
**优点**：
|
||||
## Deploy Steps
|
||||
|
||||
- ✅ 无需硬编码 fallback 值
|
||||
- ✅ 自动适配 Vercel 和 GitHub Pages
|
||||
- ✅ 构建时和运行时都正确
|
||||
### Vercel
|
||||
|
||||
## 部署步骤
|
||||
1. Push code to GitHub.
|
||||
2. Import the repo in Vercel (or connect it).
|
||||
3. Vercel will build automatically (see `vercel.json`).
|
||||
|
||||
### Vercel 部署
|
||||
Vercel usually sets `VERCEL=1` automatically.
|
||||
|
||||
1. 推送代码到 GitHub
|
||||
2. Vercel 会自动检测 `vercel.json` 配置
|
||||
3. 自动构建并部署
|
||||
4. 访问 `https://your-project.vercel.app`
|
||||
### GitHub Pages
|
||||
|
||||
**环境变量**：Vercel 自动设置 `VERCEL=1`
|
||||
|
||||
### GitHub Pages 部署
|
||||
|
||||
1. 配置 GitHub Pages 设置：
|
||||
- Source: `gh-pages` 分支
|
||||
- 或使用 GitHub Actions 从 `main` 分支部署
|
||||
|
||||
2. 构建命令：
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
3. 访问 `https://datawhalechina.github.io/easy-vibe`
|
||||
|
||||
## 验证部署
|
||||
|
||||
部署后检查以下链接是否正常：
|
||||
|
||||
- [ ] 首页能正常访问
|
||||
- [ ] 导航栏链接能正确跳转
|
||||
- [ ] 首页卡片"查看详情"链接正确
|
||||
- [ ] 语言切换功能正常
|
||||
- [ ] 图片资源能正常加载
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q: Vercel 部署后链接变成 `/easy-vibe/cn/...` 导致 404
|
||||
|
||||
**原因**：Vercel 环境变量未正确设置
|
||||
|
||||
**解决**：
|
||||
|
||||
1. 检查 Vercel 项目设置中 `Environment Variables`
|
||||
2. 确保 `VERCEL` = `1` 已设置（通常自动设置）
|
||||
3. 重新部署
|
||||
|
||||
### Q: GitHub Pages 部署后所有链接 404
|
||||
|
||||
**原因**：缺少 `/easy-vibe/` base 路径
|
||||
|
||||
**解决**：
|
||||
|
||||
1. 检查 `docs/.vitepress/config.mjs` 中的 base 配置
|
||||
2. 确保 GitHub Pages 环境下 `isVercel = false`
|
||||
3. 重新构建并部署
|
||||
|
||||
### Q: 本地预览链接缺少 `/easy-vibe/` 前缀
|
||||
|
||||
**原因**：使用了错误的预览命令
|
||||
|
||||
**解决**：
|
||||
1. Configure GitHub Pages for the repo.
|
||||
2. Build:
|
||||
|
||||
```bash
|
||||
# 错误
|
||||
npm run preview # 默认端口 4173，但路径可能不对
|
||||
|
||||
# 正确
|
||||
npm run build
|
||||
npm run preview # 访问 http://localhost:4173/easy-vibe/
|
||||
```
|
||||
|
||||
3. Verify the published site: `https://datawhalechina.github.io/easy-vibe`
|
||||
|
||||
## Post-Deploy Checklist
|
||||
|
||||
- Home page loads.
|
||||
- Navbar links navigate correctly.
|
||||
- Locale switching works.
|
||||
- Images load correctly.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Vercel URLs include `/easy-vibe/...` and return 404
|
||||
|
||||
Cause: `VERCEL` env var is missing or not equal to `1`.
|
||||
|
||||
Fix:
|
||||
|
||||
1. Check Vercel project settings -> Environment Variables.
|
||||
2. Ensure `VERCEL=1`.
|
||||
3. Redeploy.
|
||||
|
||||
### GitHub Pages returns 404 for all routes
|
||||
|
||||
Cause: missing `/easy-vibe/` base path in the build.
|
||||
|
||||
Fix:
|
||||
|
||||
1. Check `docs/.vitepress/config.mjs` base logic.
|
||||
2. Ensure the GitHub Pages build uses `base = '/easy-vibe/'`.
|
||||
3. Rebuild and redeploy.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user