Vortex's blog

一枚主题切换按钮的实现始末

Wed, 29 Jul 2026 00:00:00 GMT

在现代浏览器中，让网页响应系统明暗主题很简单：

:root {
  color-scheme: light dark;
}

这是原生层面的，例如，它会让你的浏览器默认滚动条也变色。

用户代理样式中就有深色模式下的样式，无需定制的话，这就足够让页面提供深色模式了。

color-scheme 在 2022 年广泛可用，light dark 声明网页同时提供浅色和深色模式。配合媒体查询，就能完整地定制：

@media (prefers-color-scheme: dark) {
  :root {
    color: white;
  }
}

这已经是前端程序员们多年以来梦寐以求的了，过去还得写两套 CSS 来回切换。

考虑到通常只是需要修改颜色，2024 年广泛可用的 light-dark() 进一步简化了代码：

:root {
  color-scheme: light dark;
  color: light-dark(black, white);
}

简洁、现代，一切都很美好，确实就是最完美的解决方案了。

被打破的完美

遗憾的是，尽管 Windows 原生有明暗主题，但一直不支持动态切换。要知道苹果设备甚至是支持以日出日落的时间来动态切换的。

对于一个随机 Windows 用户，它的系统永远是浅色模式。我们辛辛苦苦适配度深色模式他是享受不上的。

我高度怀疑这就是支持明暗主题的网站，基本都要提供“系统”“浅色”“深色”三个选项的原因。

无论出于什么原因，让网站支持用户手动切换明暗主题仍具有必要性，这篇文章就是我的开发经验总结。

手动设置明暗主题

想要手动设置明暗主题倒也简单，用 JavaScript 改变 color-scheme 的值即可，我的初版方案是这样的：

<button data-theme="light dark">system</button>
<button data-theme="light">light</button>
<button data-theme="dark">dark</button>

<script>
  let userTheme = localStorage.getItem('user-theme') ?? 'light dark'
  document.documentElement.style.colorScheme = userTheme

  document.querySelectorAll('[data-theme]').forEach(btn => {
    btn.addEventListener('click', () => {
      userTheme = btn.dataset.theme
      document.documentElement.style.colorScheme = userTheme
      localStorage.setItem('user-theme', userTheme)
    })
  })
</script>

documentElement 相当于 CSS 中的 :root。

将值存进 localStorage 来保存选中的主题，当用户未曾设置时，默认跟随系统。

超级讨厌的页面闪烁

似乎静态页面一旦涉及逻辑，我就要花一半时间的去和抖动和闪烁做斗争。

真实开发是组件化的，脚本的加载晚于 HTML 结构，上述代码会产生时序问题：

初始为 light
HTML 应用 light
JS 设置为 dark
HTML 应用 dark（页面闪烁）

解决方案是让脚本设置 colorScheme 早于 HTML 渲染的时间：

初始为 light
JS 设置为 dark
HTML 应用 dark

对于本站采用的 Astro 框架，提取需要的部分设置为内联即可：

<script is:inline>
  const userTheme = localStorage.getItem('user-theme') ?? 'light dark'
  document.documentElement.style.colorScheme = userTheme
</script>

主题选择器

功能实现后，顺手用 Popover API 写一个主题选择器：

<button popovertarget="theme-select">system</button>

<div id="theme-select" popover>
  <button data-theme="light dark">system</button>
  <button data-theme="light">light</button>
  <button data-theme="dark">dark</button>
</div>

<p class="light">当前处于亮色模式</p>
<p class="dark">当前处于暗色模式</p>

用现代特性就都用，再上锚点定位：

[popovertarget] {
  anchor-name: --theme-button;
}

#theme-select {
  position-anchor: --theme-button;
  position-area: bottom span-right;
  top: 4px; /* 拉开间距 */

  /* 避免覆盖隐藏时默认的 display: none */
  &:popover-open {
    display: flex;
    flex-direction: column;
  }
}

不得不说锚点定位是真方便。

在明在暗？

开头提到的媒体查询 prefers-color-scheme，它查询的永远是系统的明暗状态。

当系统为 light 时，即使声明 :root { color-scheme: dark }，也不会让 prefers-color-scheme: dark 条件生效。

我们若仍想写条件样式，只能绕过媒体查询，自行维护一个能被 CSS 响应的状态。自然的想法是在 documentElement 上设置自定义数据属性：

const userTheme = localStorage.getItem('user-theme') ?? 'light dark'
const media = matchMedia('(prefers-color-scheme: light)')
const systemTheme = media.matches ? 'light' : 'dark'
const currentTheme = userTheme === 'light dark' ? systemTheme : userTheme

document.documentElement.style.colorScheme = userTheme
document.documentElement.dataset.currentTheme = currentTheme

document.querySelectorAll('[data-theme]').forEach(btn => {
  btn.addEventListener('click', () => {
    const userTheme = btn.dataset.theme
    const currentTheme = userTheme === 'light dark' ? systemTheme : userTheme

    document.documentElement.style.colorScheme = userTheme
    document.documentElement.dataset.currentTheme = currentTheme
    localStorage.setItem('user-theme', userTheme)
  })
})

这里的关键是用 userTheme === 'light dark' ? systemTheme : userTheme 确定页面呈现的主题，systemTheme 从 matchMedia 取值，与媒体查询结果相同。

现在又可以写条件样式了：

:root[data-current-theme='dark'] {
  color: white;
}

light-dark() 不受影响，因为它读取的就是 color-scheme。

大功告成前的最后一步

系统明暗状态可能会变化，因此需要处理 media 的 change 事件来更新状态：

media.addEventListener('change', () => {
  if (userTheme !== 'light dark') return

  const currentTheme = media.matches ? 'light' : 'dark'
  document.documentElement.dataset.currentTheme = currentTheme
})

说起来，这篇文章我从深色模式写到了浅色模式……

写在最后

最后拼出来的东西并不复杂，但这条看似简单的路，沿途也藏着不少小坑。

指针入门

Thu, 23 Jul 2026 00:00:00 GMT

理解指针，首先要理解内存。

内存

内存是什么？这是一个简化的内存模型：

每一个格子代表一个内存单位，为了区分，我们给它们编上序号。

现在，我们可以在内存中保存数据了。例如，我们希望 1 号格子保存着 1：

为避免混淆，我们统一让序号加上 & 前缀。现在，内存位置为 &1 的格子，保存的值为 1。

变量

为方便指称，我们给存着 1 的格子取一个名字，例如叫它 number：

这其实就对应着代码：

var number = 1

程序获取变量 number 的值，也就是获取地址 &1 的值，其值为 1。

指针

现在，观察这种情况：

我们发现，内存位置为 &2 的格子，保存的值为 &1。同样给它取个名字，例如叫 point：

程序获取变量 point 的值，也就是获取地址 &2 的值，其值为 &1。

像 point 这样储存着地址的变量，我们称之为“指针变量”，它储存的值，就是“指针”。

可以简单地认为，指针就是地址。

取地址

上面的图示对应着代码：

var number = 1
var point = &number

若只是获取 number，值为 1；当获取 &number 时，值为 number 的地址。

point 是一个指针变量，其值 &number 是一个地址，也就是一个指针，我们将 & 称为“取地址”。

试着打印它们：

var number = 1
fmt.Println(number) // 1

var point = &number
fmt.Println(point) // 0x7e4f7e61e020 (&1)

形如 0x7e4f7e61e020 是地址的实际位置，每次运行不固定。

解引用

通常来说，拿到地址不是我们的目的，而是要获取地址上的值：

var number = 1
fmt.Println(number) // 1

var point = &number
fmt.Println(point) // 0x47e35b71e020 (&1)

var value = *point
fmt.Println(value) // 1

与 & 取地址相对，将 * 称为“解引用”。

可以简单地认为，解引用就是从地址取值。

声明指针类型

在前面的代码中，我们省略了类型声明，若将其补全：

var number int = 1
fmt.Println(number) // 1

var point *int = &number
fmt.Println(point) // 0x47e35b71e020

var value int = *point
fmt.Println(value) // 1

在 C 语言中，语法为 int *point = &number;

因此，在指针语境下，符号 * 有两种不同的语义：

声明指针变量的类型
解引用

对于 var point *int，表示指针变量 point 的类型是 *int；对于 *point，表示从 point 指向的地址取值。

练习

var number = 1
fmt.Println(number)  // #1
fmt.Println(&number) // #2

var point = &number
fmt.Println(point)   // #3
fmt.Println(*point)  // #4

观察上面的代码，回答哪两两打印相同。

答案

#1 #4; #2 #3

RimSage：面向 Agent 的 RimWorld 源码检索工具

Tue, 27 Jan 2026 00:00:00 GMT

如果你曾使用 AI 辅助开发 Mod，你会发现，主流 LLM 在编程“能力”上是没有问题的，但常犯“知识”错误：使用不存在的 RimWorld API。

很大程度上，这不能怪 LLM，它当然只能依赖互联网中已经存在的资料来训练和检索知识，这势必让它掌握的可能是过时、错误乃至虚假的 API。

一个自然的想法是，“我们可以先将所有的源码喂给 LLM 呀，这样它不就全知全能了吗？”理论上确实如此，但实际面临两个问题：

模型的上下文窗口有限。目前（2026年1月）的主流 LLM 上下文窗口集中在 256K 左右，而 RimWorld 的源码，光 C# 就超过一百万行，XML 更是四百多万行，即使是有 2M 上下文的 Grok 4 Fast，也是远远无法吞下如此庞大的代码量的。

上下文越长，模型表现越差。理想情况下，应提供给LLM尽可能少的必要消息。尽管不是越短的上下文越好，但更长的上下文往往是坏味道。无关的、冗余的信息只是噪音，它们不仅浪费 Tokens，还会降低 LLM 的输出表现¹：

业界早有解决上述问题的成熟方案，即建立代码库索引。实际上，你用 Argument Code、Cursor 或 Claude Code 等 AI 客户端打开 RimWorld 的源码仓库，你就享受到了。但这仍存在一些不足之处。首先，这要求你反编译一份 RimWorld 源码，并将其作为Agent的工作目录，这就存在不便之处。其次，这种检索方式基于通用方案，未对 RimWorld 的特定架构做针对设计，效率较差。再者，面对如此庞大的体量，不仅难以保证检索的质量和效果，还会消耗大量 Tokens。

RimSage 因上述思考而生。它是我开发的 MCP Server，为 Agent 提供一系列工具，让其像专业程序员那样在 RimWorld 源码中高效检索信息，掌握真相。

https://www.humanlayer.dev/blog/writing-a-good-claude-md ↩

RimWorld 1.6 版本新建 Mod 工程的最佳实践

Wed, 06 Aug 2025 00:00:00 GMT

RimWorld 1.6 版本在底层上做了一些改进，我们制作模组时也可以与之共进！

在过去，新建模组工程的标准做法是下载 full framework 4.7.2，这在新版本仍稳健可靠。但不再是固定步骤！依据 RimWorld 官方开发团队的建议，我将为大家介绍在新版本创建项目的新流程。

注意：你将会看到我在 macOS 上演示步骤，但在 Windows 上的操作是完全一致（甚至更简）的；我的 IDE 是 Rider，但步骤在 Visual Studio 上也是类似的。

配置环境

打开 Rider，点击左下角的“配置”，再点击“设置”：

在侧边栏中点击“环境”，你会看到：

需要确保 .NET 已经安装（不显示 Install 按钮）；如果你与我一样使用 macOS，需要一并安装 Mono。检查无误后，点击右下角“保存”关闭界面。

新建解决方案

点击“新建解决方案”，在配置面板，几个注意的地方：

建议勾选“将解决方案和项目放在同一目录中”；
目标框架暂时选择至最新版本；

确认无误后，点击右下角“创建”以新建工程。

引入依赖

我们将不再依赖于本地的 RimWorld .dll 文件，而是使用 Krafs.Rimworld.Ref nuget 包导入，这将平台无关，且构建性能更佳。

如果 Rider 左侧边栏中没有 Nuget 按钮，你可能需要手动显示它，或者使用命令行安装：

dotnet add package Krafs.Rimworld.Ref --version 1.6.4543

确认无误后，点击右下角的“安装”以添加依赖到本地；如果你在上一步采用命令行，效果是一样的。

更改编译目标

Rimworld 1.6 版本利用了 Unity 的跨平台原生编译能力，例如，Rimworld 将会原生运行在 Apple Silicon 芯片上。

Rimworld 本体的构建目标为 framework 4.0，这意味着 4.x 都是有效的。net48 等效于 framework 4.8。

你可以自由选择 C# 的语言版本，只要不在代码中使用 Rimworld 不兼容的运行时 API。

在完成上述操作后，我们会在依赖项中看到所有需要的依赖。

修改编译输出路径

我们还剩最后一步，将项目的构建路径定位到 Mod/[YourMod]/Assembiles 中。右键项目（C# 图标），点击属性，在侧边栏中依次点击“Debug｜AnyCPU”，你将会看见：

将“输出路径”修改到正确的地方，这跟过去是一样的。对于 “Debug”，请取消勾选“调试符号”，我们永远也用不到它。上述的路径修改在“Release｜AnyCPU”也重复一遍。

构建项目

确保前述所有步骤无误后，我们进行构建。你会在输出目录看见这样的目录结构：

你会发现嵌套着一个 net48 文件夹，里面才是 .dll 文件。RimWorld 会自动读取，你无需做任何操作，这代表着一切顺利 🎉

以上便是 Rimworld 1.6 版本的新建模组工程的最佳实践。