Qoder Background — 为 Qoder IDE 打造的专属背景图插件

让你的 Qoder 编辑器拥有个性化背景图，支持全屏/侧边栏/面板等多区域、图片轮播、暗色主题自适应。

目录

• • @[TOC](目录)
  • 为什么需要这个插件
  • • 原因一：文件完整性校验 (Checksum)
    • 原因二：扩展 API 差异
    • 原因三：文件协议差异
    • 我们的解决方案
  • 功能特性
  • 效果展示
  • • 全屏背景
    • 多区域背景
  • 下载与安装
  • • 下载
    • 安装
  • 配置与使用
  • • 快速开始
    • • 使用自己的图片
      • 开启轮播
      • 多区域同时配置
      • 使用内置图片
    • 支持的 5 个区域
    • 配置参数
    • 图片路径格式
    • 应用配置
  • 技术原理简述
  • • 注入方式
    • 图片处理
    • 轮播实现
    • 暗色主题自适应
  • 常见问题
  • 许可协议

为什么需要这个插件

vscode-background 是 VS Code 生态中非常受欢迎的背景图扩展（100 万+ 安装量），但它无法在 Qoder 中正常工作。经过对源码的深入分析，我们发现了 3 个关键原因：

原因一：文件完整性校验 (Checksum)

Qoder 的featureFlags.json中包含关键文件的 SHA256 校验值：

{"checksums":{"vs/workbench/workbench.desktop.main.js":"RC5k/103qaDF...","vs/workbench/workbench.desktop.main.css":"ZzndmPa1h/vb...","vs/code/electron-browser/workbench/workbench.html":"HMczP8qp+nYZ..."}}

vscode-background v2 通过向workbench.desktop.main.js末尾追加 JavaScript 代码来注入背景图样式。修改后文件校验值不匹配，Qoder 会触发安全告警甚至拒绝加载。

原因二：扩展 API 差异

vscode-background 是标准 VS Code 扩展，依赖vscode.workspace.getConfiguration()等 API 读取配置。Qoder 虽然基于 VS Code fork，但其扩展环境可能不完整兼容所有 VS Code API，导致扩展激活失败或配置读取异常。

原因三：文件协议差异

VS Code 使用vscode-file://vscode-app/协议访问本地文件，而 Qoder 的product.json中urlProtocol是qoder。虽然 Qoder 内部 JS 仍然使用vscode-file（因为是 fork），但扩展环境中的vscode.Uri行为可能不同，导致本地图片路径解析失败。

我们的解决方案

针对以上问题，我们开发了Qoder Background— 一个 Qoder 专属的背景图扩展：

功能特性

• 多区域背景— 全屏 / 侧边栏 / 面板 / 编辑器 / 辅助栏，每个区域独立配置
• 内置图片— 开箱即用，安装后无需配置即可看到默认背景
• 文件夹扫描— 指定文件夹路径，自动扫描所有图片用于轮播
• 轮播模式— 纯 CSS@keyframes动画实现，零 JS 性能消耗
• 随机展示— 每次应用配置时随机打乱图片顺序
• 暗色主题自适应— 浅色主题正常叠加，深色主题自动切换mix-blend-mode: screen
• CSP 兼容— 本地图片自动转 base64 内嵌，绕过 Electron 安全策略
• settings.json 配置— 通过 Qoder 原生设置系统管理所有参数

效果展示

全屏背景

多区域背景

下载与安装

下载

发行包说明：下载的文件是一个文件夹，包含：

• qoder-background-0.1.3.vsix— 扩展安装包
• README.md/README.en.md— 中英文使用说明
• images/logo.jpg— 插件 Logo

安装

方式一：命令行安装（推荐）

qoder --install-extension qoder-background-0.1.3.vsix

方式二：图形界面安装

1. 打开 Qoder
2. 按Ctrl+Shift+P→ 输入Extensions: Install from VSIX...
3. 选择下载的.vsix文件
4. 按Ctrl+Shift+P→Reload Window重载窗口

安装后默认即可看到全屏背景图（使用内置图片），无需任何配置。

配置与使用

快速开始

安装后打开设置文件：Ctrl+Shift+P→Open Settings (JSON)

使用自己的图片

{"qoder-background.fullscreen":{"images":["D:/my-wallpapers"],"opacity":0.1,"size":"cover","position":"center"}}

开启轮播

{"qoder-background.fullscreen":{"images":["D:/my-wallpapers"],"opacity":0.15,"interval":10,"random":true}}

每 10 秒自动切换一张背景图，随机顺序。

多区域同时配置

{"qoder-background.fullscreen":{"images":["D:/fullscreen-bg.jpg"],"opacity":0.1},"qoder-background.sidebar":{"images":["D:/sidebar-bg.jpg"],"opacity":0.08},"qoder-background.editor":{"images":["D:/editor-bg.png"],"useFront":false}}

使用内置图片

{"qoder-background.fullscreen":{"images":["builtin:images"],"opacity":0.1,"interval":10}}

支持的 5 个区域

配置参数

全局配置：

全屏区域 (fullscreen)专属参数：

轮播说明：当interval > 0且images包含多张图片时启用，纯 CSS 实现，最多 10 张。仅全屏区域支持轮播。

侧边栏 / 面板 / 辅助栏参数：

注意：这些区域不支持轮播，interval和random参数无效。

编辑器区域专属参数：

注意：编辑器区域不支持轮播，没有opacity/size/position参数。

图片路径格式

应用配置

修改 settings.json 后，需要应用才能生效（配置变更不会自动写入 workbench.html）：

1. 命令面板：Ctrl+Shift+P→Background: 应用背景图并重载→Reload Window
2. 状态栏按钮：点击右下角Background按钮
3. 自动提示：autoApply开启时，保存设置后自动注入并重载
4. 快捷脚本：node apply-from-settings.js（开发调试用）

技术原理简述

注入方式

采用HTML 注入而非 JS 注入：

• vscode-background v2 向workbench.desktop.main.js追加 JS 代码 → 触发 Qoder 的 checksum 校验
• 我们向workbench.html插入<style>标签 → 不受 JS checksum 影响
• workbench.html 的 CSP 允许'unsafe-inline'样式，天然兼容

图片处理

本地图片自动转为 base64 data URL：

用户配置: "D:/wallpapers/bg.jpg" ↓ normalizeImagePath() 文件读取 → toString('base64') ↓ data:image/jpeg;base64,/9j/4AAQSkZJRg... ↓ 写入 CSS: background-image: url('data:...')

这样绕过了 Qoder CSP 中img-src不包含file:协议的限制。

轮播实现

由于 CSP 的script-src不允许'unsafe-inline'，无法注入 JS，因此轮播采用纯 CSS 方案：

• 多图层叠加：body::after+body::before+div元素
• 每个图层关联独立的@keyframes动画
• 通过 opacity 关键帧控制同一时刻只显示一个图层
• 图片间有平滑淡入淡出过渡

暗色主题自适应

body{--qoder-bg-mix-blend-mode:unset;}body:has(> .monaco-workbench.vs-dark){--qoder-bg-mix-blend-mode:screen;}

通过 CSS:has()选择器检测深色主题的.vs-dark类，自动切换混合模式，避免在暗色背景上图片不可见。

常见问题

Q: 修改设置后不生效？
A: 需要执行Background: 应用背景图并重载命令或Reload Window。如果autoApply为true，保存后会自动应用。

Q: 背景图太淡/太浓？
A: 调整opacity值。推荐：全屏 0.05~0.3，侧边栏/面板 0.05~0.15。

Q: 轮播不工作？
A: 确保interval> 0 且images有多张图片（或指向含多张图片的文件夹）。轮播最多 10 张。

Q: 提示"安装似乎已损坏"？
A: 正常现象，扩展已自动隐藏该告警。如仍出现，可安装 vscode-fix-checksums。

Q: Qoder 更新后背景消失了？
A: Qoder 升级会覆盖 workbench.html。升级后重新执行Background: 应用背景图并重载即可恢复。

许可协议

MIT License