Electron shell 模块详解：跨平台打开文件、外部链接、回收站与快捷方式

Electron 的 shell 模块负责把应用与操作系统桌面环境对接起来：用默认程序打开文件和外部协议链接、在文件管理器中定位文件、将文件移入回收站、发出提示音，以及在 Windows 上读写 .lnk 快捷方式。本文基于 shell 模块 API 文档 完整梳理其全部方法、参数与返回值，并结合当前仓库的 C++ 实现与测试用例，说明各方法在 Windows、macOS、Linux 三平台上的底层执行路径。读完后你可以直接在自己的 Electron 应用中安全地调用桌面集成 API，并理解每个行为背后的实现机制。

模块定位与可用进程

shell 模块提供的函数都与桌面集成（desktop integration）相关。文档给出的最基础用法是在用户默认浏览器中打开一个 URL：

const { shell } = require('electron')

shell.openExternal('https://github.com')

关于可用进程，官方文档 明确标注：

• 主进程（Main）；
• 渲染进程（Renderer），但非沙箱环境下才可用。

警告：shell 模块虽可在渲染进程中使用，但在沙箱化（sandboxed）的渲染进程中不会生效。

从源码结构看，这一结论有清晰的实现依据。JS 侧的入口非常薄——lib/common/api/shell.ts 仅一行：

const shell = process._linkedBinding('electron_common_shell');

它直接把 C++ 侧名为 electron_common_shell 的 linked binding 暴露为 JS 模块，并在 lib/common/api/module-list.ts 中注册（{ name: 'shell', loader: () => require('./shell') }）。binding 的实际注册发生在 shell/common/api/electron_api_shell.cc 的 Initialize 函数中：

dict.SetMethod("showItemInFolder", &platform_util::ShowItemInFolder);
dict.SetMethod("openPath", &OpenPath);
dict.SetMethod("openExternal", &OpenExternal);
dict.SetMethod("trashItem", &TrashItem);
dict.SetMethod("beep", &platform_util::Beep);
#if BUILDFLAG(IS_WIN)
dict.SetMethod("writeShortcutLink", &WriteShortcutLink);
dict.SetMethod("readShortcutLink", &ReadShortcutLink);
#endif

注意最后一段 #if BUILDFLAG(IS_WIN) 编译开关——writeShortcutLink / readShortcutLink 只在 Windows 构建中存在，与文档中方法名后的 _Windows_ 标注一致。沙箱渲染进程无法访问此类系统级能力，这也是文档强调"non-sandboxed only"的原因。

shell.showItemInFolder(fullPath)

• fullPath string

在文件管理器中显示给定文件，并尽量把该文件选中。这是一个无返回值、无 Promise 的同步入口，典型用途是"打开文件夹并定位到当前文件"。

各平台由 platform_util::ShowItemInFolder 实现。以 Windows 为例，shell/common/platform_util_win.cc 会把任务投递到专门的 COM STA 线程池线程执行（路径分隔符会先做 NormalizePathSeparators 归一化）：

void ShowItemInFolder(const base::FilePath& full_path) {
  CreateShellOperationTaskRunner()->PostTask(
      FROM_HERE, base::BindOnce(&ShowItemInFolderOnWorkerThread,
                                full_path.NormalizePathSeparators()));
}

Linux 侧则由 ShowItemHelper 完成（见 shell/common/platform_util_linux.cc），且断言必须在 UI 线程调用。

shell.openPath(path)

• path string

返回 Promise<string>：失败时 resolve 为包含错误信息的字符串，成功时为 ""。作用是按桌面默认方式打开给定文件。

API 历史：该方法前身是 shell.openItem，后经 electron/electron#20682 对应的破坏性变更重命名为 shell.openPath（见原文档内嵌的 YAML history）。

其 Promise 封装在 shell/common/api/electron_api_shell.cc 中：回调无论成功失败都会 resolve（错误信息作为字符串值返回，而不是 reject），这一点在使用时要特别注意——不能只用 catch 捕获失败，需要检查 resolve 出来的字符串是否为空：

const error = await shell.openPath('/path/to/file')
if (error) {
  console.error('打开失败：', error)
}

平台实现细节（从源码结构看）：

• Windows：OpenPathOnThread 会先判断目标是目录还是文件——目录走 ui::win::OpenFolderViaShell，文件走 ui::win::OpenFileViaShell（见 shell/common/platform_util_win.cc）。源码注释还解释了为何相关任务使用 CONTINUE_ON_SHUTDOWN：当系统弹出"需要新应用才能打开此链接"等对话框时 ShellExecuteEx 可能无限期阻塞，若采用默认的 SKIP_ON_SHUTDOWN 策略，app.quit() 会被卡死直到用户关闭该对话框（CreateShellOperationTaskRunner 处有详细说明）。
• Linux：通过 XDGOpen 调用 xdg-open 完成，且以文件所在目录作为工作目录（shell/common/platform_util_linux.cc）。

shell.openExternal(url[, options])

• url string - 在 Windows 上最长 2081 个字符。
• options Object (optional)
  • activate boolean (optional) macOS - true 表示把打开的应用带到前台。默认 true。
  • workingDirectory string (optional) Windows - 工作目录。
  • logUsage boolean (optional) Windows - 标记一次"用户主动发起"的启动，从而启用常用程序等行为的跟踪。默认 false。

返回 Promise<void>。作用是按桌面默认方式打开外部协议 URL——例如 mailto: 链接会用用户的默认邮件客户端打开。

API 历史（见原文档内嵌 history）：activate 选项随 PR #4508 加入；workingDirectory 随 PR #15065 加入；logUsage 随 PR #37139 加入。

选项解析与默认值

JS 传入的 options 在 OpenExternal 中被逐项取出：

platform_util::OpenExternalOptions options;
gin_helper::Dictionary obj;
if (args->GetNext(&obj)) {
  obj.Get("activate", &options.activate);
  obj.Get("workingDirectory", &options.working_dir);
  obj.Get("logUsage", &options.log_usage);
}

默认值定义在 shell/common/platform_util.h 的结构体里，与文档标注完全一致：

struct OpenExternalOptions {
  bool activate = true;
  base::FilePath working_dir;
  bool log_usage = false;
};

失败路径由统一的 OnOpenFinished 处理：错误信息为空则 resolve，否则 RejectWithErrorMessage（electron_api_shell.cc）。测试用例验证了这一点：当系统没有能处理该 URL 的应用时，shell.openExternal(url) 会被 reject，错误信息匹配 /No application found to open URL/（见 spec/api-shell-spec.ts）。

各平台执行路径

• Linux：OpenExternal 对 mailto: 协议走 xdg-email，其余 scheme 走 xdg-open；两者都是"不等待退出"方式启动，即 Promise 在应用被拉起后即返回，而不会等目标程序窗口关闭（shell/common/platform_util_linux.cc）。
• Windows：同样先投递到 COM STA 任务线程（shell/common/platform_util_win.cc），在 OpenExternalOnWorkerThread 中携带 activate、working_dir、log_usage 选项完成启动。

典型使用场景：拦截页面内 window.open / <a target="_blank">，把 URL 交给系统默认浏览器而不是新开一个 Chromium 窗口：

const { shell, BrowserWindow } = require('electron')

const win = new BrowserWindow()
win.webContents.setWindowOpenHandler(({ url }) => {
  if (url.startsWith('https://')) {
    shell.openExternal(url)   // 交给系统默认浏览器
  }
  return { action: 'deny' }
})

shell.trashItem(path)

• path string - 要移入回收站的项的路径。

返回 Promise<void>：操作完成时 resolve；删除请求项的过程中出错时 reject。

该方法把路径移入操作系统对应的回收位置——macOS 上是 Trash，Windows 上是回收站（Recycle Bin），Linux 上是桌面环境相关的位置。文档特别提醒：路径必须使用平台默认的路径分隔符（Windows 上是反斜杠），建议使用 node:path 的 path.resolve() 保证在所有文件系统上正确工作。

API 历史：shell.trashItem 是 shell.moveItemToTrash 的替代（见原文档内嵌 history，对应 PR #25114 的破坏性变更）。

底层 TrashItem 封装见 electron_api_shell.cc：成功 resolve，失败则带错误信息 reject——这与 openPath"总是 resolve"的行为形成对比。

各平台实现差异（从源码结构看）：

• Windows：通过 COM 的 IFileOperation 接口执行删除，操作标志同时设置了 FOFX_RECYCLEONDELETE（进入回收站）、FOFX_ADDUNDORECORD（可撤销）、FOFX_SHOWELEVATIONPROMPT（UAC 保护文件弹提权提示）等（shell/common/platform_util_win.cc）。
• Linux：先检查环境变量 ELECTRON_TRASH 作为可覆写的回收站命令；否则根据桌面环境自动选择实现——KDE4/KDE5 用 kioclient5 move <file> trash:/，KDE3 用 kioclient，trash-cli 用 trash-put，gvfs-trash 用同名命令（已废弃但仍存在），其余默认使用 gio trash（shell/common/platform_util_linux.cc）。这意味着 Linux 上 ELECTRON_TRASH 环境变量是定制回收站行为的官方口子。

测试用例验证了基本行为与错误路径：正常文件能成功移入回收站，不存在的文件会导致 trashItem reject（见 spec/api-shell-spec.ts）。

shell.beep()

播放提示音。无参数、无返回值。

Linux 平台实现值得一提：platform_util_linux.cc 中，gdk_display_beep 实际是一个桩函数，其函数指针可能为 nullptr，因此每次调用前都要确保通过 electron::InitializeElectron_gdk(gtk::GetLibGdk()) 初始化，以避免崩溃；没有可用显示时则静默返回。

Windows 快捷方式管理

以下两个方法仅在 Windows 平台可用。

shell.writeShortcutLink(shortcutPath[, operation], options) Windows

• shortcutPath string
• operation string (optional) - 默认 create，可取：
  • create - 创建新快捷方式，必要时覆盖已有快捷方式。
  • update - 仅更新已有快捷方式的指定属性。
  • replace - 覆盖已有快捷方式，若快捷方式不存在则失败。
• options ShortcutDetails

返回 boolean——快捷方式是否成功创建/更新。

operation 字符串在 electron_api_shell.cc 的 gin Converter 中映射到 Chromium 的 base::win::ShortcutOperation 枚举：空串或 "create" 对应 kCreateAlways，"update" 对应 kUpdateExisting，"replace" 对应 kReplaceExisting，其他取值会直接转换失败并抛错。实际写盘由 base::win::CreateOrUpdateShortcutLink 完成，执行前会初始化 COM（ScopedCOMInitializer）并允许一次性阻塞调用（electron_api_shell.cc）。

三种语义在测试中有精确验证（spec/api-shell-spec.ts）：

• 对不存在的快捷方式执行 update 返回 false，随后 create 返回 true 并成功写入；
• 对不存在的快捷方式执行 replace 返回 false；
• 已有快捷方式时，update 只改传入的属性（测试断言结果为 { ...shortcutOptions, ...change }），而 replace 会用新选项整体覆盖旧内容。

shell.readShortcutLink(shortcutPath) Windows

• shortcutPath string

返回 ShortcutDetails 对象，解析 shortcutPath 处的快捷方式；任何错误发生时抛出异常（注意：测试用例中 readShortcutLink('not-exist') 会抛错，调用前建议先校验文件存在）。

ShortcutDetails 的完整字段（见 docs/api/structures/shortcut-details.md）：

字段	类型	说明
target	string	快捷方式启动的目标
cwd	string (optional)	工作目录，默认为空
args	string (optional)	启动 target 时应用的参数，默认为空
description	string (optional)	快捷方式的描述，默认为空
icon	string (optional)	图标路径，可以是 DLL 或 EXE；必须与 iconIndex 同时设置，默认为空（使用 target 的图标）
iconIndex	number (optional)	icon 为 DLL/EXE 时的资源 ID，默认 0
appUserModelId	string (optional)	Application User Model ID，默认为空
toastActivatorClsid	string (optional)	Toast Activator CLSID，参与 Action Center 所需

实现上，ReadShortcutLink 通过 base::win::ResolveShortcutProperties(path, PROPERTIES_ALL, ...) 读取全部属性并逐字段填充返回字典；toastActivatorClsid 只有在解析结果的 options 位掩码含 PROPERTIES_TOAST_ACTIVATOR_CLSID 时才会出现在返回值中（electron_api_shell.cc）。写入方向则把 ShortcutDetails 各字段逐一映射为 ShortcutProperties 的 setter（target→set_target、cwd→set_working_dir、args→set_arguments、description→set_description、icon+iconIndex→set_icon、appUserModelId→set_app_id、toastActivatorClsid→set_toast_activator_clsid）。

一个典型应用是安装结束后为用户创建桌面/开始菜单快捷方式：

// 仅 Windows
const { shell } = require('electron')

const ok = shell.writeShortcutLink('C:\\Users\\Public\\Desktop\\MyApp.lnk', 'create', {
  target: 'C:\\Program Files\\MyApp\\myapp.exe',
  args: '--launch-from=desktop',
  icon: 'C:\\Program Files\\MyApp\\myapp.exe',
  iconIndex: 0,
  appUserModelId: 'com.example.myapp'
})

if (!ok) {
  console.error('创建快捷方式失败')
}

const details = shell.readShortcutLink('C:\\Users\\Public\\Desktop\\MyApp.lnk')
console.log(details.target, details.appUserModelId)

相关源码与测试索引

内容	路径
API 文档（本文骨架）	docs/api/shell.md
ShortcutDetails 结构定义	docs/api/structures/shortcut-details.md
JS 模块入口（linked binding）	lib/common/api/shell.ts
模块注册表	lib/common/api/module-list.ts
JS 方法绑定与选项解析	shell/common/api/electron_api_shell.cc
平台 API 声明与默认值	shell/common/platform_util.h
Windows 平台实现	shell/common/platform_util_win.cc
Linux 平台实现	shell/common/platform_util_linux.cc
行为测试用例	spec/api-shell-spec.ts

小结

shell 模块是 Electron 应用中唯一直接触达操作系统桌面行为的 JS 层 API：openExternal 把外部 URL 交给系统（macOS 上可控制是否前台激活，Windows 上可指定工作目录与用量跟踪），openPath 用默认方式打开本地文件并以字符串报告错误，showItemInFolder 在文件管理器中定位文件，trashItem 跨平台移入回收站（Linux 上支持 ELECTRON_TRASH 覆写），beep 发出提示音，Windows 专属的 writeShortcutLink / readShortcutLink 则以 create/update/replace 三种语义完整管理 .lnk 快捷方式。使用时需记住两条硬性约束：方法只在主进程与非沙箱渲染进程中可用；openPath 失败靠 resolve 的字符串表达而 trashItem/openExternal 失败靠 reject，两者的错误处理写法不同。