gowallpaper/README.md

GoWallpaper

GoWallpaper 是一个仅面向 Windows 的轻量托盘壁纸切换工具。它通过 HTTP GET 请求随机图片 API，将响应图片缓存到程序同目录，并支持手动刷新、定时刷新以及缓存历史前后切换。

功能

• 启动后隐藏到 Windows 托盘并显示运行提示
• 托盘菜单手动刷新壁纸
• 上一张、下一张缓存壁纸
• 可开关并自定义间隔的自动切换
• 可配置最大缓存数量
• 保持系统壁纸样式，或选择填充、适应、拉伸、平铺、居中、跨区
• 当前用户开机自动启动
• 命名互斥体阻止多开
• 首次运行自动创建 config.json 和 cache 目录

API 要求

API 必须支持公开的 HTTP GET 请求，并直接在响应体中返回 JPEG、PNG、GIF 或 WebP 图片。程序允许标准 HTTP 重定向，单张图片最大 50 MB。

首次运行时 API 地址为空，程序会自动打开设置窗口。也可以退出程序后直接编辑同目录下的 config.json：

{
  "api_url": "https://example.com/random-image",
  "auto_change_enabled": false,
  "interval_minutes": 30,
  "max_cache_count": 10,
  "wallpaper_style": "keep",
  "start_with_windows": false
}

wallpaper_style 可使用 keep、fill、fit、stretch、tile、center 或 span。

构建

需要 Go 1.25 或兼容版本，以及 rsrc：

go install github.com/akavel/rsrc@latest

项目统一通过 build.ps1 执行格式化、测试和构建，禁止绕过脚本直接执行编译命令：

# 格式化、测试并构建 dist/GoWallpaper.exe
.\build.ps1

# 仅格式化和测试
.\build.ps1 -TestOnly

# 清理构建产物
.\build.ps1 -Clean

构建完成后请将 GoWallpaper.exe 放在普通可写目录中运行。由于配置及缓存严格保存在程序同目录，不建议放入 Program Files 等通常需要管理员权限的目录。

运行文件

GoWallpaper.exe
config.json
cache/
  index.json
  20260731_120000_000000000.jpg

缓存索引记录历史顺序和当前位置。程序退出后不会清空缓存。