wechat-versions完全指南：从环境搭建到自动化部署

一、项目核心价值解析

wechat-versions项目为Mac用户提供微信历史版本管理解决方案，通过任务自动化工具链实现官方安装包的自动获取、版本信息提取与历史归档。该项目采用Shell脚本与GitHub Actions（持续集成服务）构建自动化工作流，帮助用户追溯特定版本微信客户端，解决版本兼容性问题或功能需求。

二、环境准备与依赖检查

基础环境要求

• 操作系统：macOS 10.14+
• 核心依赖：
  • Git（版本控制工具）
  • curl（网络请求工具）
  • GitHub账户（用于Actions配置）

环境验证命令

# 检查Git安装状态（需2.20.0+版本）
git --version && \
# 验证curl可用性
curl --version && \
# 确认bash环境
echo $BASH_VERSION

💡 为什么需要这样做：Git用于代码拉取，curl处理网络请求，这些工具是执行自动化脚本的基础依赖。

新手常见误区：直接跳过环境检查步骤，导致后续脚本执行时出现"command not found"错误。建议先运行验证命令确保所有依赖可用。

三、快速部署操作流程

Step 1/4：获取项目代码

执行以下命令克隆代码仓库（约200MB）：

git clone https://gitcode.com/gh_mirrors/we/wechat-versions.git && cd wechat-versions

Step 2/4：配置密钥凭证

登录GitHub账户，在项目仓库依次进入Settings > Secrets and variables > Actions，添加以下密钥：

密钥名称	说明	默认值
GITHUB_TOKEN	仓库操作认证令牌	无（需生成）
WECHAT_DOWNLOAD_URL	微信官方下载地址	https://dldir1.qq.com/weixin/mac/WeChatMac.dmg

💡 为什么需要这样做：GITHUB_TOKEN提供API操作权限，WECHAT_DOWNLOAD_URL确保能获取最新安装包地址。

Step 3/4：工作流配置

项目已预置工作流文件在.github/workflows目录，包含：

• version-check.yml：版本检测与更新流程
• release-upload.yml：安装包上传至Releases

如需自定义执行频率，可修改文件中schedule字段：

# 示例：每日凌晨3点执行检查
on:
  schedule:
    - cron: '0 3 * * *'

Step 4/4：手动触发执行

在项目根目录运行版本检测脚本：

# 赋予执行权限（仅首次运行需要）
chmod +x ./scripts/destVersionForMac.py && \
# 执行版本获取脚本
./scripts/destVersionForMac.py --verbose

四、进阶配置选项

配置参数对照表

参数名称	配置文件	说明	默认值
DOWNLOAD_DIR	scripts/config.sh	安装包缓存目录	./downloads
VERSION_FILE	scripts/config.sh	版本记录文件	versions.json
MAX_HISTORY	scripts/config.sh	最大保存版本数	20
NOTIFY_ENABLE	scripts/notify.sh	通知功能开关	true

自定义通知方式

修改scripts/notify.sh文件配置通知渠道：

# 支持邮件/钉钉/企业微信等通知方式
NOTIFY_CHANNEL="email"
# 邮件通知配置
EMAIL_RECIPIENTS="[e-mail]"

五、效果检验与常见问题

验证方法

1. 版本记录检查：

cat versions.json | jq '.versions[0]'

应显示最新版本号及hash值

2. Releases页面验证： 登录GitHub仓库，查看Releases标签页是否有新上传的安装包资产

常见问题解决

Q1：脚本执行提示权限不足

解决：执行chmod +x ./scripts/*.sh赋予所有脚本执行权限

Q2：GitHub Actions执行失败

排查步骤：

1. 检查Secrets配置是否完整
2. 查看Actions日志：Actions > 工作流名称 > 具体任务 > 展开日志
3. 验证WECHAT_DOWNLOAD_URL是否有效

Q3：版本记录不更新

可能原因：

• 网络连接问题导致下载失败
• 官方下载链接已变更
• 本地缓存未清理

解决：手动清除缓存并重新执行：

rm -rf ./downloads && ./scripts/destVersionForMac.py --force

六、自动化工作原理

项目核心工作流基于以下流程实现：

1. 定时触发：通过GitHub Actions的schedule机制定期执行
2. 版本检测：destVersionForMac.py脚本对比本地记录与官方最新版本
3. 文件处理：下载并校验安装包完整性
4. 版本归档：更新版本记录并上传至Releases
5. 状态通知：通过notify.sh发送执行结果通知

这种设计确保了版本获取的及时性与自动化，减少人工维护成本。