map-client-vue/RELEASE_SCRIPT_GUIDE.md

release.sh 使用指南

📋 概述

release.sh 是一个自动化发布脚本，用于简化版本发布流程。

✨ 功能特性

v2.0 新特性

• ✅ 自动字符集降级 - 检测到字符集问题时自动使用英文版本
• ✅ 详细错误提示 - 提供清晰的错误信息和解决方案
• ✅ Release 验证 - 创建后验证并显示访问链接
• ✅ 手动创建指南 - API 失败时提供详细的手动步骤

核心功能

1. 检查 Git 分支和工作区状态
2. 从 release.md 提取最新版本信息
3. 创建并推送 Git 标签
4. 通过 Gitea API 自动创建 Release
5. 智能处理字符集兼容性问题

🚀 使用方法

前置要求

1. 安装 jq 命令

# macOS
brew install jq

# Ubuntu/Debian
sudo apt-get install jq

# CentOS/RHEL
sudo yum install jq

2. 设置 Gitea 访问令牌

export GITEA_TOKEN="your_token_here"

获取令牌方法：

• 登录 Gitea
• 设置 → 应用 → 生成新令牌
• 权限选择：repo (完整仓库访问)

3. 准备 release.md

确保 release.md 文件存在，且最新版本在文件末尾：

## v1.0.2
...

## v1.0.3
...

执行发布

# 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 命令"

解决方案：

# 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: "工作区有未提交的更改"

解决方案：

# 查看状态
git status

# 选项1: 提交更改
git add .
git commit -m "准备发布"

# 选项2: 暂存更改
git stash

# 选项3: 放弃更改
git reset --hard

Q3: "未设置 GITEA_TOKEN"

解决方案：

# 临时设置（当前会话）
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

# ❌ 错误
GITEA_TOKEN="73c2e2cd8ca86dbeaebdeaef77cbab3564d5122a"

# ✅ 正确
export GITEA_TOKEN="73c2e2cd8ca86dbeaebdeaef77cbab3564d5122a"

2. 限制 Token 权限

   • 只授予必要的 repo 权限
   • 定期轮换 Token

3. 不要提交 Token 到 Git

# 添加到 .gitignore
echo '.env' >> .gitignore
echo '*.token' >> .gitignore

📚 相关文档

• release.md - 版本发布记录
• GITEA_RELEASE_SUCCESS.md - 成功案例
• Gitea API 文档

🆕 版本历史

v2.0 (2025-10-15)

• ✨ 添加字符集自动降级处理
• ✨ 改进错误提示和日志输出
• ✨ 添加 Release 创建验证
• ✨ 添加手动创建指南
• ✨ 检查 jq 命令是否安装

v1.0 (2024-xx-xx)

• 🎉 初始版本
• ✅ 基本的发布功能

---

维护者: douboer
更新时间: 2025-10-15