ByteNoteByteNote
字

字节笔记本

2026年2月22日

macos-wallpaper：macOS 桌面壁纸管理工具

#开源工具

本文介绍 macos-wallpaper，一个用于管理 macOS 桌面壁纸的命令行工具和 Swift 包。该项目由 Sindre Sorhus 开发维护，提供了简洁高效的 API 来设置和获取 macOS 桌面壁纸，支持多显示器配置和多种缩放模式。

项目简介

macos-wallpaper 是一个开源的 macOS 壁纸管理工具，采用 Swift 语言编写。截至目前，该项目在 GitHub 上已获得 695 stars 和 40 forks。它既可以作为命令行工具直接使用，也可以作为 Swift Package 集成到你的 macOS 应用中。

该项目的核心优势在于能够正确处理各种壁纸设置场景，包括当壁纸设置为目录时的获取操作，这是许多同类工具无法妥善处理的边缘情况。

核心特性

  • 双模式支持：同时提供 CLI 命令行工具和 Swift Package 两种使用方式
  • 多显示器支持：可为所有屏幕、主屏幕或指定索引的屏幕设置壁纸
  • 多种缩放模式：支持 auto、fill、fit、stretch、center 等多种缩放选项
  • 纯色壁纸：支持设置纯色作为桌面背景
  • 沙盒兼容：在沙盒应用中能够优雅地处理数据库访问限制
  • 跨架构支持：原生支持 Apple Silicon 和 Intel 处理器

技术栈

  • Swift：主要开发语言（100%）
  • Xcode：开发环境，需要最新版本
  • Swift Package Manager：依赖管理

安装指南

CLI 工具安装

通过 Homebrew 安装（推荐）

bash
brew install wallpaper

手动安装

  1. 访问 GitHub Releases 下载最新版本
  2. 将二进制文件移动到 /usr/local/bin 目录

Swift Package 集成

在 Package.swift 中添加依赖：

swift
.package(url: "https://github.com/sindresorhus/macos-wallpaper", from: "2.3.2")

或在 Xcode 中通过 File → Add Package Dependencies 添加。

系统要求

  • macOS 10.14.4 或更高版本
  • 构建需要最新版本的 Xcode 和 macOS

CLI 使用示例

查看帮助信息

bash
$ wallpaper --help
USAGE: wallpaper <subcommand>

OPTIONS:
  --version               Show the version.
  -h, --help              Show help information.

SUBCOMMANDS:
  get                     Get current wallpaper images.
  set                     Set image as wallpaper.
  set-solid-color         Set solid color as wallpaper.
  screens                 Get a list of available screens.

设置壁纸

bash
# 为所有屏幕设置壁纸
wallpaper set unicorn.jpg

# 仅为主屏幕设置壁纸
wallpaper set unicorn.jpg --screen main

# 为指定索引的屏幕设置壁纸
wallpaper set unicorn.jpg --screen 1

设置纯色壁纸

bash
# 设置蓝色纯色背景
wallpaper set-solid-color 0000ff

# 为特定屏幕设置纯色
wallpaper set-solid-color ff0000 --screen 0

获取当前壁纸

bash
# 获取所有屏幕的当前壁纸路径
wallpaper get

# 获取主屏幕的壁纸
wallpaper get --screen main

缩放模式选项

bash
# 使用 fill 模式填充屏幕
wallpaper set image.jpg --scale fill

# 使用 fit 模式适应屏幕
wallpaper set image.jpg --scale fit

# 使用 stretch 模式拉伸
wallpaper set image.jpg --scale stretch

# 居中显示
wallpaper set image.jpg --scale center

可用的缩放模式：

  • auto：自动选择（默认）
  • fill：填充屏幕，可能裁剪图片
  • fit：适应屏幕，保持比例
  • stretch：拉伸以填满屏幕
  • center：居中显示，不缩放

查看可用屏幕

bash
wallpaper screens

Swift API 使用示例

基础用法

swift
import Wallpaper

// 设置图片壁纸
let imageURL = URL(filePath: "/path/to/image.jpg")
try! Wallpaper.set(imageURL, screen: .main, scale: .fill)

// 设置纯色壁纸
let solidColor = NSColor.blue
try! Wallpaper.set(solidColor, screen: .main)

// 获取当前壁纸
let currentWallpaper = try! Wallpaper.get(screen: .main)
print(currentWallpaper)

屏幕选项

swift
// 为所有屏幕设置
Wallpaper.set(imageURL, screen: .all)

// 仅为主屏幕设置
Wallpaper.set(imageURL, screen: .main)

// 为指定索引的屏幕设置
Wallpaper.set(imageURL, screen: .index(1))

缩放选项

swift
Wallpaper.set(imageURL, scale: .auto)     // 自动
Wallpaper.set(imageURL, scale: .fill)     // 填充
Wallpaper.set(imageURL, scale: .fit)      // 适应
Wallpaper.set(imageURL, scale: .stretch)  // 拉伸
Wallpaper.set(imageURL, scale: .center)   // 居中

开发指南

本地运行

bash
swift run wallpaper

构建发布版本

bash
swift build --configuration=release --arch arm64 --arch x86_64 \
  && mv .build/apple/Products/Release/wallpaper .

此命令会构建通用二进制文件，同时支持 Apple Silicon (arm64) 和 Intel (x86_64) 架构。

注意事项

  1. 沙盒应用限制：在沙盒应用中，库会优雅地处理数据库访问限制。获取当前壁纸时，如果壁纸设置为目录，可能返回目录路径而非具体图片文件。

  2. 权限要求：应用需要具有访问文件系统的权限才能设置壁纸。

  3. 多显示器处理：使用 --screen 参数可以精确控制要为哪个显示器设置壁纸。

相关项目

  • wallpaper - 跨平台桌面壁纸管理工具（基于本项目的二进制文件）
  • macos-trash - 将文件移动到废纸篓
  • do-not-disturb - 控制 macOS 勿扰模式

项目链接

许可证

MIT License © Sindre Sorhus

开源工具
上一篇

在 Flutter 中显示 Python OpenCV 视频流

下一篇

macos-wallpaper：macOS 桌面壁纸管理工具

分享: