Electrobun macOS 原生毛玻璃效果插件

本文介绍 electrobun-macos-native-blur，一个为 Electrobun 桌面应用框架添加 macOS 原生毛玻璃模糊效果的插件项目。

项目简介

electrobun-macos-native-blur 是一个开源的 macOS 原生窗口效果扩展库，由开发者 mayfer 创建。该项目解决了 Electron 类桌面应用框架在 macOS 上难以实现原生视觉效果的痛点，让基于 Web 技术的桌面应用也能拥有媲美原生应用的视觉体验。

截至目前，该项目在 GitHub 上已获得 128 stars，主要使用 TypeScript (49.2%) 和 Objective-C++ (41.7%) 编写。

核心特性

1. 原生 macOS 毛玻璃效果 (NSVisualEffectView)

通过调用 macOS 原生 API NSVisualEffectView，为 Electrobun 应用窗口添加系统级的毛玻璃模糊背景效果，支持多种材质风格。

2. 原生交通灯按钮对齐

实现 macOS 窗口左上角关闭/最小化/最大化按钮（Traffic Lights）的精确定位，与自定义标题栏完美融合。

3. 原生窗口阴影恢复

解决透明窗口默认丢失阴影的问题，通过 ensureWindowShadow 函数恢复原生窗口阴影效果。

4. 原生拖拽区域支持

使用 Cocoa 原生拖拽区域实现标题栏拖动，支持跨 Spaces（虚拟桌面）移动窗口，体验与原生应用完全一致。

5. React/Tailwind 友好

UI 层保持简洁，原生效果通过底层桥接实现，不影响前端技术栈的选择。

技术栈

安装指南

前置要求

• macOS 系统
• Bun 运行时（≥ 1.0）
• Xcode Command Line Tools（用于编译原生代码）

安装步骤

# 克隆仓库
git clone https://github.com/mayfer/electrobun-macos-native-blur.git
cd electrobun-macos-native-blur

# 安装依赖
bun install

快速开始

开发模式

# 标准开发模式
bun run dev

# 带 Vite HMR 的开发模式
bun run dev:hmr

生产构建

# 完整构建（包含原生效果编译）
bun run build

# 仅构建原生效果
bun run build:native-effects

# 生产频道构建
bun run build:prod

核心实现原理

原生桥接架构

由于 Electrobun 默认只提供基础的 titleBarStyle: "hiddenInset" 和 transparent: true 选项，没有完整的公开 Vibrancy API，该项目通过以下方式实现原生效果：

1. Objective-C++ 原生层：native/macos/window-effects.mm 实现 Cocoa 原生代码
2. Bun FFI 桥接：通过 bun:ffi 加载编译后的动态库
3. TypeScript 封装层：src/bun/index.ts 提供友好的 JavaScript API

关键 API

// 启用窗口毛玻璃效果
enableWindowVibrancy(windowPtr)

// 确保窗口阴影正常显示
ensureWindowShadow(windowPtr)

// 设置交通灯按钮位置
setWindowTrafficLightsPosition(windowPtr, x, yFromTop)

// 设置原生拖拽区域
setNativeWindowDragRegion(windowPtr, x, height)

项目结构

electrobun-macos-native-blur/
├── src/
│   ├── bun/
│   │   └── index.ts          # Electrobun 主进程代码
│   └── mainview/
│       └── App.tsx           # React UI 组件
├── native/
│   └── macos/
│       └── window-effects.mm # Objective-C++ 原生实现
├── scripts/
│   └── build-macos-effects.sh # 构建脚本
├── electrobun.config.ts      # Electrobun 配置
└── package.json

配置调优

交通灯按钮位置

在 src/bun/index.ts 中调整以下常量：

const MAC_TRAFFIC_LIGHTS_X = 20  // 水平位置
const MAC_TRAFFIC_LIGHTS_Y = 16  // 垂直位置（距顶部）

标题栏几何对齐

在 src/mainview/App.tsx 中调整：

// 标题栏高度
<header className="h-12 ...">

// 左侧预留空间给原生按钮
<div className="pl-24 ...">

提示：修改标题栏高度或内边距后，需要同步调整 MAC_TRAFFIC_LIGHTS_Y 以保持按钮视觉居中。

拖拽区域配置

const MAC_NATIVE_DRAG_REGION_X = 80      // 拖拽区域起始 X
const MAC_NATIVE_DRAG_REGION_HEIGHT = 40 // 拖拽区域高度

使用示例

基础用法

import { BrowserWindow } from 'electrobun'
import { loadNativeEffects } from './native-effects'

// 加载原生效果库
const nativeLib = loadNativeEffects()

// 创建窗口
const win = new BrowserWindow({
  titleBarStyle: 'hiddenInset',
  transparent: true,
  // ... 其他配置
})

// 启用毛玻璃效果
nativeLib.enableWindowVibrancy(win.getNativeWindowHandle())

// 设置交通灯按钮位置
nativeLib.setWindowTrafficLightsPosition(
  win.getNativeWindowHandle(),
  20,  // x
  16   // y from top
)

注意事项

1. 系统设置影响：原生毛玻璃效果依赖于 macOS 的透明度设置。如果模糊效果不明显，请检查：

   • 系统设置 → 辅助功能 → 显示器 → 降低透明度（应关闭）

2. 平台限制：该原生桥接仅支持 macOS，其他平台会回退到正常行为。

3. 快捷键支持：Cmd+W 关闭行为通过 src/bun/index.ts 中的 macOS 应用菜单配置实现。

构建流程详解

bun run build 执行以下步骤：

1. 编译原生效果：

   bashCopy

   xcrun clang++ -dynamiclib -fobjc-arc -framework Cocoa \
     native/macos/window-effects.mm \
     -o src/bun/libMacWindowEffects.dylib

2. Vite 构建：打包前端资源

3. Electrobun 构建：生成应用包

非 macOS 主机：脚本会创建一个占位 dylib 文件，确保 Electrobun 的复制步骤正常执行。

项目链接

• GitHub 仓库：https://github.com/mayfer/electrobun-macos-native-blur
• Electrobun 官网：https://electrobun.dev
• Bun FFI 文档：https://bun.sh/docs/api/ffi

总结

electrobun-macos-native-blur 为 Electrobun 开发者提供了一套完整的 macOS 原生窗口效果解决方案。通过 Bun FFI 桥接 Objective-C++ 代码，在保持 Web 技术栈开发效率的同时，实现了媲美原生应用的视觉体验。对于希望在 macOS 上构建高质量桌面应用的开发者来说，这是一个值得参考的优秀范例。