map-client-vue/RELEASE_SCRIPT_CHANGES.md

release.sh v2.0 更新说明

🎯 更新概述

将 ~/pubsh/release.sh 复制到项目并升级为 v2.0，主要解决字符集兼容性问题和改进用户体验。

✨ 主要改进

1. 智能字符集处理

问题：Gitea 服务器 MySQL 数据库不支持完整 UTF-8，导致中文 + Emoji 的 Release 创建失败

解决方案：

# 首次尝试：使用原始内容（中文）
curl ... -d "$JSON_PAYLOAD"

# 失败时：自动降级为英文
if [[ "$response_body" == *"Conversion from collation"* ]]; then
  # 使用英文版本重试
  curl ... -d "$JSON_PAYLOAD_EN"
fi

效果：

• ✅ 自动检测字符集错误
• ✅ 无需手动干预
• ✅ 确保 Release 一定能创建成功

2. 详细的错误提示

Before：

❌ Release 创建失败，HTTP 500

After：

❌ Release 创建失败，HTTP 500
📄 错误信息: {"message":"Error 3988..."}

💡 手动创建步骤:
   1. 访问: https://biboer.cn/gitea/gavin/map-client-vue/releases
   2. 点击 '新建发布'
   3. 选择标签: v1.0.3
   4. 从 release.md 复制说明

3. Release 创建验证

新增功能：

if [ "$http_code" -eq 201 ]; then
  release_url=$(echo "$response_body" | jq -r '.html_url')
  echo "✅ Release 创建成功: $VERSION"
  echo "🔗 Release 地址: $release_url"
fi

效果：

• ✅ 立即显示 Release 链接
• ✅ 确认创建成功
• ✅ 方便快速访问

4. 完善的发布总结

新增输出：

📊 发布总结:
  ✅ Git 标签已推送
  ✅ 代码已推送到远程
  ✅ Gitea Release 已创建

🔗 访问地址:
  - Release: https://biboer.cn/gitea/.../releases/tag/v1.0.3
  - 标签列表: https://biboer.cn/gitea/.../tags
  - 提交历史: https://biboer.cn/gitea/.../commits/branch/main

🚀 用户升级指南:
  git pull origin main
  cd web && npm install
  npm run dev

5. 工具依赖检查

新增检查：

if ! command -v jq &> /dev/null; then
  echo "❌ 错误：未安装 jq 命令"
  echo "💡 安装方法："
  echo "   macOS: brew install jq"
  exit 1
fi

6. 详细的脚本文档

新增头部说明：

# ==========================================
# Git 自动发布脚本 v2.0
# ==========================================
# 功能：
#   1. 检查分支和工作区状态
#   2. 从 release.md 提取版本信息
#   ...
#
# 使用方法：
#   export GITEA_TOKEN="your_token_here"
#   ./release.sh
# ==========================================

📋 修改清单

文件	状态	说明
release.sh	✅ 已修改	升级到 v2.0
RELEASE_SCRIPT_GUIDE.md	✅ 新建	完整使用指南
RELEASE_SCRIPT_CHANGES.md	✅ 新建	本文档

🔄 使用对比

Before (v1.0)

# 1. 设置 token
export GITEA_TOKEN="xxx"

# 2. 运行脚本
~/pubsh/release.sh

# 3. 遇到字符集错误
❌ Release 创建失败，HTTP 500

# 4. 需要手动去 Gitea 创建 Release
# 😓 麻烦...

After (v2.0)

# 1. 设置 token
export GITEA_TOKEN="xxx"

# 2. 运行脚本
./release.sh

# 3. 自动处理字符集问题
⚠️ 检测到字符集问题，尝试使用英文版本...
✅ Release 创建成功 (英文版): v1.0.3
🔗 Release 地址: https://...
💡 提示: 可以在 Gitea Web 界面手动编辑添加中文说明

# 4. 完成！
🎉 发布完成！

🎯 解决的问题

1. ✅ 字符集转换错误 - 自动降级为英文
2. ✅ 错误信息不清晰 - 显示详细错误和解决方案
3. ✅ 手动步骤繁琐 - 提供清晰的手动创建指南
4. ✅ 缺少验证 - 显示 Release URL 确认成功
5. ✅ 依赖不明确 - 检查 jq 命令是否安装
6. ✅ 文档缺失 - 提供完整使用指南

🚀 测试结果

测试用例 1：正常发布（中文成功）

$ export GITEA_TOKEN="xxx"
$ ./release.sh

✅ 分支: main
✅ 工作区干净
📝 版本号: v1.0.3
✅ 已创建 tag v1.0.3
🚀 推送到远程...
🔄 尝试创建 Release (使用中文内容)...
✅ Release 创建成功: v1.0.3
🎉 发布完成！

测试用例 2：字符集降级（英文成功）

$ export GITEA_TOKEN="xxx"
$ ./release.sh

✅ 分支: main
✅ 工作区干净
📝 版本号: v1.0.3
✅ 已创建 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 界面手动编辑添加中文说明
🎉 发布完成！

测试用例 3：完全失败（提供手动步骤）

$ export GITEA_TOKEN="invalid"
$ ./release.sh

✅ 分支: main
✅ 工作区干净
📝 版本号: v1.0.3
✅ 已创建 tag v1.0.3
🚀 推送到远程...
🔄 尝试创建 Release (使用中文内容)...
❌ Release 创建失败，HTTP 401
📄 错误信息: {"message":"Unauthorized"}

💡 手动创建步骤:
   1. 访问: https://biboer.cn/gitea/gavin/map-client-vue/releases
   2. 点击 '新建发布'
   3. 选择标签: v1.0.3
   4. 从 release.md 复制说明

📚 相关文档

• release.sh - 发布脚本本身
• RELEASE_SCRIPT_GUIDE.md - 完整使用指南
• GITEA_RELEASE_SUCCESS.md - v1.0.3 发布成功案例

🔜 未来改进

• 支持更多 Git 托管平台（GitHub, GitLab）
• 添加交互式模式（询问版本号）
• 支持预发布版本（prerelease）
• 自动生成 Release Notes（基于提交记录）
• 支持附件上传（编译产物）
• 集成 CI/CD 工作流

📝 提交建议

git add release.sh RELEASE_SCRIPT_GUIDE.md RELEASE_SCRIPT_CHANGES.md
git commit -m "🔧 升级 release.sh 到 v2.0

✨ 新功能
- 智能字符集处理（自动降级为英文）
- 详细错误提示和手动步骤
- Release 创建验证和 URL 显示
- 工具依赖检查（jq）

📚 文档
- 添加 RELEASE_SCRIPT_GUIDE.md 使用指南
- 添加 RELEASE_SCRIPT_CHANGES.md 变更说明

🐛 修复
- 修复字符集转换错误导致 Release 创建失败
- 改进错误信息输出"

---

更新时间: 2025-10-15
版本: v2.0
状态: ✅ 已测试并验证