Skip to content

Commit 244eca0

Browse files
xiumubaixiumubai
committed
feat: 添加多平台部署配置和文档
添加 GitHub Pages、Vercel 和 Netlify 的部署配置 创建部署指南文档 DEPLOYMENT.md 更新 VitePress 配置以支持不同环境 添加构建和部署脚本到 package.json
1 parent 4944701 commit 244eca0

6 files changed

Lines changed: 355 additions & 10 deletions

File tree

‎.github/workflows/deploy.yml‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
name: Deploy VitePress site to Pages
2+
3+
on:
4+
# 在推送到 main 分支时触发
5+
push:
6+
branches: [main]
7+
# 允许手动触发工作流
8+
workflow_dispatch:
9+
10+
# 设置 GITHUB_TOKEN 的权限，允许部署到 GitHub Pages
11+
permissions:
12+
contents: read
13+
pages: write
14+
id-token: write
15+
16+
# 只允许一个并发部署，跳过正在运行和最新队列之间的运行队列
17+
concurrency:
18+
group: pages
19+
cancel-in-progress: false
20+
21+
jobs:
22+
# 构建工作
23+
build:
24+
runs-on: ubuntu-latest
25+
steps:
26+
- name: Checkout
27+
uses: actions/checkout@v4
28+
with:
29+
fetch-depth: 0 # 如果未启用 lastUpdated，则不需要
30+
31+
- name: Setup Node
32+
uses: actions/setup-node@v4
33+
with:
34+
node-version: 20
35+
cache: npm
36+
cache-dependency-path: docs/package-lock.json
37+
38+
- name: Setup Pages
39+
uses: actions/configure-pages@v4
40+
41+
- name: Install dependencies
42+
run: |
43+
cd docs
44+
npm ci
45+
46+
- name: Build with VitePress
47+
run: |
48+
cd docs
49+
npm run build
50+
env:
51+
NODE_ENV: production
52+
53+
- name: Upload artifact
54+
uses: actions/upload-pages-artifact@v3
55+
with:
56+
path: docs/.vitepress/dist
57+
58+
# 部署工作
59+
deploy:
60+
environment:
61+
name: github-pages
62+
url: ${{ steps.deployment.outputs.page_url }}
63+
needs: build
64+
runs-on: ubuntu-latest
65+
name: Deploy
66+
steps:
67+
- name: Deploy to GitHub Pages
68+
id: deployment
69+
uses: actions/deploy-pages@v4

‎DEPLOYMENT.md‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
# 部署指南
2+
3+
本文档提供了将 Python 基础编程学习文档网站部署到不同平台的详细指南。
4+
5+
## 📋 部署前准备
6+
7+
### 1. 环境要求
8+
- Node.js 18+
9+
- npm 或 yarn
10+
- Git
11+
12+
### 2. 本地构建测试
13+
```bash
14+
# 进入文档目录
15+
cd docs
16+
17+
# 安装依赖
18+
npm install
19+
20+
# 本地开发
21+
npm run dev
22+
23+
# 构建测试
24+
npm run build
25+
26+
# 预览构建结果
27+
npm run preview
28+
```
29+
30+
## 🚀 部署方案
31+
32+
### 方案一：GitHub Pages（推荐）
33+
34+
#### 自动部署（推荐）
35+
1. **启用 GitHub Pages**
36+
- 进入仓库 Settings → Pages
37+
- Source 选择 "GitHub Actions"
38+
- 配置文件已创建：`.github/workflows/deploy.yml`
39+
40+
2. **触发部署**
41+
```bash
42+
git add .
43+
git commit -m "feat: add deployment configuration"
44+
git push origin main
45+
```
46+
47+
3. **访问网站**
48+
- 部署完成后访问：`https://[username].github.io/python-awesome-basic-coding/`
49+
50+
#### 手动部署
51+
```bash
52+
# 安装 gh-pages
53+
npm install -g gh-pages
54+
55+
# 构建并部署
56+
cd docs
57+
npm run deploy:github
58+
```
59+
60+
### 方案二：Vercel
61+
62+
#### 通过 Vercel CLI
63+
1. **安装 Vercel CLI**
64+
```bash
65+
npm install -g vercel
66+
```
67+
68+
2. **登录并部署**
69+
```bash
70+
vercel login
71+
vercel --prod
72+
```
73+
74+
#### 通过 Vercel 网站
75+
1. 访问 [vercel.com](https://vercel.com)
76+
2. 连接 GitHub 仓库
77+
3. 选择项目并导入
78+
4. Vercel 会自动检测 `vercel.json` 配置
79+
5. 点击 Deploy
80+
81+
### 方案三：Netlify
82+
83+
#### 通过 Netlify CLI
84+
1. **安装 Netlify CLI**
85+
```bash
86+
npm install -g netlify-cli
87+
```
88+
89+
2. **登录并部署**
90+
```bash
91+
netlify login
92+
netlify deploy --prod
93+
```
94+
95+
#### 通过 Netlify 网站
96+
1. 访问 [netlify.com](https://netlify.com)
97+
2. 连接 GitHub 仓库
98+
3. 配置构建设置：
99+
- Build command: `cd docs && npm run build`
100+
- Publish directory: `docs/.vitepress/dist`
101+
4. 点击 Deploy
102+
103+
## ⚙️ 配置说明
104+
105+
### VitePress 配置
106+
- **base 路径**：根据部署环境自动调整
107+
- **输出目录**：`docs/.vitepress/dist`
108+
- **清理 URLs**：启用友好的 URL 格式
109+
110+
### 构建脚本
111+
- `npm run build`：标准构建
112+
- `npm run build:github`：GitHub Pages 构建（带 base 路径）
113+
- `npm run preview`：本地预览构建结果
114+
- `npm run clean`：清理构建文件
115+
116+
## 🔧 常见问题
117+
118+
### 1. 资源路径问题
119+
**问题**：部署后样式或图片无法加载
120+
121+
**解决方案**：
122+
- 检查 `base` 配置是否正确
123+
- 确保所有资源使用相对路径
124+
- 验证构建输出的路径结构
125+
126+
### 2. 路由问题
127+
**问题**：刷新页面出现 404
128+
129+
**解决方案**：
130+
- GitHub Pages：确保启用了 `cleanUrls`
131+
- Vercel/Netlify：检查重定向规则配置
132+
133+
### 3. 构建失败
134+
**问题**：部署时构建失败
135+
136+
**解决方案**：
137+
```bash
138+
# 检查 Node.js 版本
139+
node --version
140+
141+
# 清理依赖重新安装
142+
rm -rf node_modules package-lock.json
143+
npm install
144+
145+
# 本地测试构建
146+
npm run build
147+
```
148+
149+
### 4. 环境变量
150+
**问题**：不同环境需要不同配置
151+
152+
**解决方案**：
153+
- 使用 `process.env.NODE_ENV` 判断环境
154+
- 在部署平台设置环境变量
155+
- 检查 `.env` 文件配置
156+
157+
## 📊 性能优化
158+
159+
### 1. 缓存策略
160+
- 静态资源：长期缓存（1年）
161+
- HTML 文件：不缓存或短期缓存
162+
- API 响应：根据更新频率设置
163+
164+
### 2. 压缩优化
165+
- 启用 Gzip/Brotli 压缩
166+
- 图片优化和懒加载
167+
- 代码分割和按需加载
168+
169+
### 3. CDN 配置
170+
- 使用 CDN 加速静态资源
171+
- 配置合适的缓存策略
172+
- 启用 HTTP/2 和 HTTP/3
173+
174+
## 🔍 监控和维护
175+
176+
### 1. 部署监控
177+
- 设置部署通知
178+
- 监控构建时间和成功率
179+
- 配置错误报告
180+
181+
### 2. 性能监控
182+
- 使用 Lighthouse 检查性能
183+
- 监控页面加载时间
184+
- 检查 Core Web Vitals
185+
186+
### 3. 定期维护
187+
- 更新依赖包
188+
- 检查安全漏洞
189+
- 优化构建配置
190+
191+
## 📞 技术支持
192+
193+
如果在部署过程中遇到问题，可以：
194+
195+
1. 查看构建日志获取详细错误信息
196+
2. 检查各平台的官方文档
197+
3. 在项目仓库提交 Issue
198+
4. 参考社区解决方案
199+
200+
---
201+
202+
**注意**：首次部署可能需要几分钟时间，请耐心等待。部署完成后，通常在 1-2 分钟内即可访问网

‎docs/.vitepress/config.js‎

Lines changed: 8 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,10 @@ import { defineConfig } from 'vitepress'
33
export default defineConfig({
44
title: 'Python基础编程学习',
55
description: 'Python基础编程完整学习教程',
6-
base: '/',
6+
base: process.env.NODE_ENV === 'production' ? '/python-awesome-basic-coding/' : '/',
7+
outDir: '../dist',
78
ignoreDeadLinks: true,
9+
cleanUrls: true,
810

911
themeConfig: {
1012
logo: '/logo.svg',
@@ -19,14 +21,11 @@ export default defineConfig({
1921
sidebar: {
2022
'/guide/': [
2123
{
22-
text: '📚 教程导航',
23-
items: [
24-
{ text: '🏠 教程首页', link: '/guide/' },
25-
{ text: '📖 学习指南', link: '/guide/learning-guide' }
26-
]
24+
text: '🏠 教程导航',
25+
link: '/guide/',
2726
},
2827
{
29-
text: '🔤 基础语法',
28+
text: '1. 基础语法',
3029
items: [
3130
{ text: '📝 变量和类型', link: '/guide/01-variables-and-types/' },
3231
{ text: '🔢 运算符', link: '/guide/02-operators/' },
@@ -35,15 +34,15 @@ export default defineConfig({
3534
]
3635
},
3736
{
38-
text: '🔀 控制结构',
37+
text: '2. 控制结构',
3938
items: [
4039
{ text: '❓ 条件语句', link: '/guide/05-conditions/' },
4140
{ text: '🔄 循环', link: '/guide/06-loops/' },
4241
{ text: '⏹️ 循环控制', link: '/guide/07-loop-control/' }
4342
]
4443
},
4544
{
46-
text: '📊 数据结构',
45+
text: '3. 数据结构',
4746
items: [
4847
{ text: '📋 列表', link: '/guide/08-lists/' },
4948
{ text: '📦 元组', link: '/guide/09-tuples/' },

‎docs/package.json‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,11 @@
66
"scripts": {
77
"dev": "vitepress dev",
88
"build": "vitepress build",
9-
"preview": "vitepress preview"
9+
"preview": "vitepress preview",
10+
"build:github": "vitepress build --base /python-awesome-basic-coding/",
11+
"deploy:github": "npm run build:github && gh-pages -d .vitepress/dist",
12+
"serve": "vitepress serve",
13+
"clean": "rm -rf .vitepress/dist"
1014
},
1115
"devDependencies": {
1216
"vitepress": "^1.6.4"

‎netlify.toml‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
[build]
2+
# 构建命令
3+
command = "cd docs && npm run build"
4+
# 发布目录
5+
publish = "docs/.vitepress/dist"
6+
# Node.js 版本
7+
environment = { NODE_VERSION = "20" }
8+
9+
[build.environment]
10+
NODE_ENV = "production"
11+
12+
# 重定向规则，用于 SPA 路由
13+
[[redirects]]
14+
from = "/*"
15+
to = "/index.html"
16+
status = 200
17+
18+
# 缓存设置
19+
[[headers]]
20+
for = "/assets/*"
21+
[headers.values]
22+
Cache-Control = "public, max-age=31536000, immutable"
23+
24+
[[headers]]
25+
for = "/*.html"
26+
[headers.values]
27+
Cache-Control = "public, max-age=0, must-revalidate"
28+
29+
# 预渲染设置（可选）
30+
[build.processing]
31+
skip_processing = false
32+
[build.processing.css]
33+
bundle = true
34+
minify = true
35+
[build.processing.js]
36+
bundle = true
37+
minify = true
38+
[build.processing.html]
39+
pretty_urls = true
40+
41+
# 插件配置（可选）
42+
# [[plugins]]
43+
# package = "netlify-plugin-lighthouse"

0 commit comments

Comments
 (0)