实现的效果

🎨 自动主题切换

  • 启动时智能检测：Neovim 启动时自动检测当前桌面环境的深浅色模式

  • 无缝主题匹配：

    • 浅色模式 → 自动应用 Catppuccin Latte（浅色主题）
    • 深色模式 → 自动应用 Catppuccin Mocha（深色主题）
  • 视觉效果统一：编辑器主题与 Quickshell 生成的 Material Design 3 终端颜色完美协调

🎯 手动控制保留

  • 快捷键切换：

    • <leader>tl - 强制切换到浅色主题
    • <leader>td - 强制切换到深色主题

  • 命令行控制：

    • :ThemeLight - 切换到浅色主题
    • :ThemeDark - 切换到深色主题

原理

🔍 检测机制

  1. 数据源：读取 Quickshell 生成的颜色配置文件

    • 位置：~/.local/state/quickshell/user/generated/colors.json
    • 内容：包含完整的 Material Design 3 颜色调色板

  2. 亮度计算：

    -- 提取背景色（如 #f6fafe 或 #101417）
local r = tonumber(hex:sub(1, 2), 16) or 0
local g = tonumber(hex:sub(3, 4), 16) or 0  
local b = tonumber(hex:sub(5, 6), 16) or 0

-- 使用 ITU-R BT.709 标准计算相对亮度
local brightness = (r * 299 + g * 587 + b * 114) / 1000

  3. 判断逻辑：

    • brightness > 128 → 浅色环境 → vim.o.background = "light"
    • brightness ≤ 128 → 深色环境 → vim.o.background = "dark"

⚙️ Neovim 内部机制

  1. background 选项：

    • Neovim 内置选项，用于告知主题当前环境类型
    • 不是自动检测器，需要手动或脚本设置

  2. 主题响应：

    background = { 
  light = "latte",    -- vim.o.background = "light" 时使用
  dark = "mocha",     -- vim.o.background = "dark" 时使用
},
  3. 自动监听：使用 OptionSet autocmd 监听 background 选项变化，实时切换主题

🔄 工作流程

Quickshell 切换日夜模式
    ↓
更新 colors.json 文件
    ↓  
Neovim 启动时读取文件
    ↓
计算背景色亮度
    ↓
设置 vim.o.background
    ↓
触发主题自动切换

注意事项

⚠️ 配置文件路径依赖

  1. Quickshell 数据路径：

    • 当前路径：~/.local/state/quickshell/user/generated/colors.json
    • 注意：如果 Quickshell 配置更改了数据生成路径，需要同步更新 Neovim 配置中的路径

  2. 检查方法：

    # 验证颜色文件是否存在
ls -la ~/.local/state/quickshell/user/generated/colors.json

# 查看当前背景色
grep '"background"' ~/.local/state/quickshell/user/generated/colors.json

🔧 配置维护

  1. 主题优先级：

    • Catppuccin 设置为 priority = 1000，确保在其他主题之前加载
    • Github-theme 设为 lazy = true，避免冲突

  2. 备用机制：

    • 如果颜色文件读取失败，默认设置为浅色模式
    • 保留手动切换功能作为备用选项

🐛 故障排除

  1. 主题不切换：

    • 检查 colors.json 文件是否存在和可读
    • 在 Neovim 中运行 :echo vim.o.background 查看检测结果
    • 使用 :messages 查看是否有错误信息

  2. 颜色不协调：

    • 检查透明背景设置：transparent_background = false
    • 确认终端颜色序列正常：cat ~/.local/state/quickshell/user/generated/terminal/sequences.txt

  3. 手动测试：

    -- 在 Neovim 中测试
:lua print(vim.fn.expand("~/.local/state/quickshell/user/generated/colors.json"))
:lua print(vim.fn.filereadable(vim.fn.expand("~/.local/state/quickshell/user/generated/colors.json")))

📂 相关文件位置

  • Neovim 主题配置：~/.config/nvim/lua/plugins/catppuccin.lua
  • Quickshell 颜色数据：~/.local/state/quickshell/user/generated/colors.json
  • 终端颜色序列：~/.local/state/quickshell/user/generated/terminal/sequences.txt
  • Quickshell 主配置：~/.config/illogical-impulse/config.json

🔄 更新维护

  1. Quickshell 更新后：检查数据文件路径是否变更
  2. Neovim 插件更新后：验证主题切换功能是否正常
  3. 系统主题更改后：重启终端和 Neovim 验证效果

本文档记录了基于 Quickshell + Kitty + Neovim + Catppuccin 的智能主题切换系统实现方案，实现了编辑器与桌面环境的主题同步。

创建时间：2025-09-04
适用环境：Arch Linux + Hyprland + Quickshell + Neovim + LazyVim