自定义 CSS 主题：修改 Kikoeru Web 界面外观

为什么要改外观

Kikoeru 默认界面是 Quasar 内置的中性配色——功能没问题但可能：

• 想做成深色主题（晚上睡前看眼睛舒服）
• 想把侧边栏宽度改窄/改宽
• 想加一些动画效果或自定义字体
• 某个元素位置不顺眼想调一下

原理

Kikoeru 前端打包后是一堆静态文件在 dist/ 目录里：

dist/
├── index.html
├── css/
│   ├── app.892d7287.css   ← 样式都在这里
│   └── vendor.xxxxx.css
└── js/
    ├── app.892d7287.js
    └── ...

每个 CSS 文件的文件名带 hash（892d7287）——每次前端重新构建，hash 会变。所以覆盖 CSS 不能硬编码文件名。

Docker 环境下改 CSS

参考 by三生的博客里的做法：

步骤一：找到当前 CSS 文件名

docker exec -it kikoeru find /usr/src/kikoeru/dist/css -type f -name "*.css"

记下输出的 app.892d7287.css 这样的文件名（hash 部分每次可能不一样）。

步骤二：提取出来改

# 拷贝到宿主机
docker cp kikoeru:/usr/src/kikoeru/dist/css/app.892d7287.css ./app.css

# 编辑
nano ./app.css

在文件末尾追加你想改的样式（或直接全局替换选择器）。比如把侧边栏改成黑色背景：

.q-layout__section--marginal { background-color: #000000; }
aside.q-drawer div.q-scrollarea>div.scroll>div { height: 0; }

步骤三：注入回容器

修改 docker-compose.yml，在 volumes 里加一行：

volumes:
  - ./sqlite:/usr/src/kikoeru/sqlite
  - ./covers:/usr/src/kikoeru/covers
  - ./config:/usr/src/kikoeru/config
  - ./app.css:/usr/src/kikoeru/dist/css/app.892d7287.css   # ← 注入
  - <voice_path>:/usr/src/kikoeru/VoiceWork

步骤四：重启

docker compose down && docker compose up -d

⚠️ 升级注意

升级前端版本后 CSS hash 会变！

• 升级 Docker 镜像 → 前端可能重新构建 → CSS 文件名变了
• 之前写的 ./app.css:/usr/src/kikoeru/dist/css/app.OLD_HASH.css 就挂了
• 升级后必须重新走一遍上面的四步流程

Windows / npm 方式

更简单——直接改 exe 同级的 dist/css/ 里的 CSS 文件就行，改完刷新浏览器看效果。没有容器隔离这一步。

可以改什么

CSS 可以改的一切：

• 配色（背景色、文字色、按钮色）
• 字体（引入自定义字体文件）
• 尺寸（侧边栏宽、封面图大小、按钮大小）
• 动画和过渡
• 隐藏某些元素（比如不想看的广告位）
• 自定义深色模式覆盖层

不能改的：

• 页面结构（DOM 节点由 Quasar 模板生成）
• JavaScript 逻辑

想改结构/逻辑得去改 kikoeru-quasar 源码重新构建（属于二次开发范畴）。