update at 2025-10-15 15:29:17
This commit is contained in:
douboer
278
RELEASE_SCRIPT_GUIDE.md
Normal file
278
RELEASE_SCRIPT_GUIDE.md
Normal file
@@ -0,0 +1,278 @@
|
||||
# release.sh 使用指南
|
||||
|
||||
## 📋 概述
|
||||
|
||||
`release.sh` 是一个自动化发布脚本，用于简化版本发布流程。
|
||||
|
||||
## ✨ 功能特性
|
||||
|
||||
### v2.0 新特性
|
||||
- ✅ **自动字符集降级** - 检测到字符集问题时自动使用英文版本
|
||||
- ✅ **详细错误提示** - 提供清晰的错误信息和解决方案
|
||||
- ✅ **Release 验证** - 创建后验证并显示访问链接
|
||||
- ✅ **手动创建指南** - API 失败时提供详细的手动步骤
|
||||
|
||||
### 核心功能
|
||||
1. 检查 Git 分支和工作区状态
|
||||
2. 从 `release.md` 提取最新版本信息
|
||||
3. 创建并推送 Git 标签
|
||||
4. 通过 Gitea API 自动创建 Release
|
||||
5. 智能处理字符集兼容性问题
|
||||
|
||||
## 🚀 使用方法
|
||||
|
||||
### 前置要求
|
||||
|
||||
1. **安装 jq 命令**
|
||||
```bash
|
||||
# macOS
|
||||
brew install jq
|
||||
|
||||
# Ubuntu/Debian
|
||||
sudo apt-get install jq
|
||||
|
||||
# CentOS/RHEL
|
||||
sudo yum install jq
|
||||
```
|
||||
|
||||
2. **设置 Gitea 访问令牌**
|
||||
```bash
|
||||
export GITEA_TOKEN="your_token_here"
|
||||
```
|
||||
|
||||
获取令牌方法：
|
||||
- 登录 Gitea
|
||||
- 设置 → 应用 → 生成新令牌
|
||||
- 权限选择：`repo` (完整仓库访问)
|
||||
|
||||
3. **准备 release.md**
|
||||
|
||||
确保 `release.md` 文件存在，且最新版本在**文件末尾**：
|
||||
|
||||
```markdown
|
||||
## v1.0.2
|
||||
...
|
||||
|
||||
## v1.0.3
|
||||
...
|
||||
```
|
||||
|
||||
### 执行发布
|
||||
|
||||
```bash
|
||||
# 1. 确保在 main 分支
|
||||
git checkout main
|
||||
|
||||
# 2. 确保工作区干净
|
||||
git status
|
||||
|
||||
# 3. 设置令牌（可选，如果已设置）
|
||||
export GITEA_TOKEN="73c2e2cd8ca86dbeaebdeaef77cbab3564d5122a"
|
||||
|
||||
# 4. 执行脚本
|
||||
./release.sh
|
||||
```
|
||||
|
||||
## 📊 执行流程
|
||||
|
||||
```
|
||||
1. 检查 jq 命令
|
||||
↓
|
||||
2. 检查 Git 分支 (必须是 main)
|
||||
↓
|
||||
3. 检查工作区状态 (必须干净)
|
||||
↓
|
||||
4. 拉取最新代码
|
||||
↓
|
||||
5. 从 release.md 提取版本
|
||||
↓
|
||||
6. 创建 Git 标签
|
||||
↓
|
||||
7. 推送标签到远程
|
||||
↓
|
||||
8. 尝试创建 Gitea Release (中文)
|
||||
↓
|
||||
失败？→ 尝试英文版本
|
||||
↓
|
||||
成功！→ 显示 Release 链接
|
||||
↓
|
||||
9. 显示发布总结
|
||||
```
|
||||
|
||||
## 🔧 字符集问题处理
|
||||
|
||||
### 问题说明
|
||||
|
||||
某些 Gitea 服务器的 MySQL 数据库配置可能不支持完整的 UTF-8 字符（如 Emoji），导致创建 Release 时出错。
|
||||
|
||||
### 自动处理流程
|
||||
|
||||
1. **首次尝试** - 使用 `release.md` 中的原始内容（中文 + Emoji）
|
||||
2. **检测错误** - 如果返回字符集转换错误
|
||||
3. **自动降级** - 使用简化的英文版本
|
||||
4. **提供链接** - 在英文版本中添加指向 `release.md` 的链接
|
||||
|
||||
### 手动编辑 Release
|
||||
|
||||
如果你想在 Release 中使用中文说明：
|
||||
|
||||
1. 访问 Gitea Release 页面
|
||||
2. 点击 "编辑" 按钮
|
||||
3. 复制 `release.md` 中对应版本的内容
|
||||
4. 粘贴并保存
|
||||
|
||||
## 📝 输出示例
|
||||
|
||||
### 成功输出
|
||||
|
||||
```
|
||||
✅ 分支: main
|
||||
✅ 工作区干净
|
||||
⬇️ 拉取远程代码...
|
||||
✅ 已同步最新代码
|
||||
📝 版本号: v1.0.3
|
||||
说明:
|
||||
发布时间: 2025-10-15
|
||||
...
|
||||
✅ 已创建 tag v1.0.3
|
||||
🚀 推送到远程...
|
||||
...
|
||||
🔄 尝试创建 Release (使用中文内容)...
|
||||
⚠️ 检测到字符集问题，尝试使用英文版本...
|
||||
✅ Release 创建成功 (英文版): v1.0.3
|
||||
🔗 Release 地址: https://biboer.cn/gitea/gavin/map-client-vue/releases/tag/v1.0.3
|
||||
💡 提示: 可以在 Gitea Web 界面手动编辑添加中文说明
|
||||
|
||||
🎉 发布完成！
|
||||
📦 版本：v1.0.3
|
||||
|
||||
📊 发布总结:
|
||||
✅ Git 标签已推送
|
||||
✅ 代码已推送到远程
|
||||
✅ Gitea Release 已创建
|
||||
|
||||
🔗 访问地址:
|
||||
- Release: https://biboer.cn/gitea/gavin/map-client-vue/releases/tag/v1.0.3
|
||||
- 标签列表: https://biboer.cn/gitea/gavin/map-client-vue/tags
|
||||
- 提交历史: https://biboer.cn/gitea/gavin/map-client-vue/commits/branch/main
|
||||
|
||||
🚀 用户升级指南:
|
||||
git pull origin main
|
||||
cd web && npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### 错误处理
|
||||
|
||||
如果 Release 创建完全失败，脚本会提供手动创建步骤：
|
||||
|
||||
```
|
||||
❌ Release 创建失败，HTTP 500
|
||||
|
||||
💡 手动创建步骤:
|
||||
1. 访问: https://biboer.cn/gitea/gavin/map-client-vue/releases
|
||||
2. 点击 '新建发布'
|
||||
3. 选择标签: v1.0.3
|
||||
4. 从 release.md 复制说明
|
||||
```
|
||||
|
||||
## 🐛 常见问题
|
||||
|
||||
### Q1: "未安装 jq 命令"
|
||||
|
||||
**解决方案**：
|
||||
```bash
|
||||
# macOS
|
||||
brew install jq
|
||||
|
||||
# 或下载二进制文件
|
||||
wget https://github.com/jqlang/jq/releases/download/jq-1.7/jq-macos-amd64
|
||||
chmod +x jq-macos-amd64
|
||||
sudo mv jq-macos-amd64 /usr/local/bin/jq
|
||||
```
|
||||
|
||||
### Q2: "工作区有未提交的更改"
|
||||
|
||||
**解决方案**：
|
||||
```bash
|
||||
# 查看状态
|
||||
git status
|
||||
|
||||
# 选项1: 提交更改
|
||||
git add .
|
||||
git commit -m "准备发布"
|
||||
|
||||
# 选项2: 暂存更改
|
||||
git stash
|
||||
|
||||
# 选项3: 放弃更改
|
||||
git reset --hard
|
||||
```
|
||||
|
||||
### Q3: "未设置 GITEA_TOKEN"
|
||||
|
||||
**解决方案**：
|
||||
```bash
|
||||
# 临时设置（当前会话）
|
||||
export GITEA_TOKEN="your_token_here"
|
||||
|
||||
# 永久设置（添加到 ~/.zshrc 或 ~/.bashrc）
|
||||
echo 'export GITEA_TOKEN="your_token_here"' >> ~/.zshrc
|
||||
source ~/.zshrc
|
||||
```
|
||||
|
||||
### Q4: "标签已存在"
|
||||
|
||||
脚本会自动删除旧标签并重新创建，无需手动处理。
|
||||
|
||||
### Q5: Release 内容是英文的
|
||||
|
||||
这是因为字符集问题自动降级了。你可以：
|
||||
1. 在 Gitea Web 界面手动编辑 Release
|
||||
2. 或者升级服务器的 MySQL 数据库配置
|
||||
|
||||
## 🔒 安全建议
|
||||
|
||||
1. **不要在脚本中硬编码 Token**
|
||||
```bash
|
||||
# ❌ 错误
|
||||
GITEA_TOKEN="73c2e2cd8ca86dbeaebdeaef77cbab3564d5122a"
|
||||
|
||||
# ✅ 正确
|
||||
export GITEA_TOKEN="73c2e2cd8ca86dbeaebdeaef77cbab3564d5122a"
|
||||
```
|
||||
|
||||
2. **限制 Token 权限**
|
||||
- 只授予必要的 `repo` 权限
|
||||
- 定期轮换 Token
|
||||
|
||||
3. **不要提交 Token 到 Git**
|
||||
```bash
|
||||
# 添加到 .gitignore
|
||||
echo '.env' >> .gitignore
|
||||
echo '*.token' >> .gitignore
|
||||
```
|
||||
|
||||
## 📚 相关文档
|
||||
|
||||
- `release.md` - 版本发布记录
|
||||
- `GITEA_RELEASE_SUCCESS.md` - 成功案例
|
||||
- [Gitea API 文档](https://docs.gitea.io/en-us/api-usage/)
|
||||
|
||||
## 🆕 版本历史
|
||||
|
||||
### v2.0 (2025-10-15)
|
||||
- ✨ 添加字符集自动降级处理
|
||||
- ✨ 改进错误提示和日志输出
|
||||
- ✨ 添加 Release 创建验证
|
||||
- ✨ 添加手动创建指南
|
||||
- ✨ 检查 jq 命令是否安装
|
||||
|
||||
### v1.0 (2024-xx-xx)
|
||||
- 🎉 初始版本
|
||||
- ✅ 基本的发布功能
|
||||
|
||||
---
|
||||
|
||||
**维护者**: douboer
|
||||
**更新时间**: 2025-10-15
|
||||
Reference in New Issue
Block a user