julia-evans

远离 Tailwind，学习构建我的 CSS 结构

Fri, 15 May 2026 00:00:00 +0000

[AI 摘要] The author describes migrating from Tailwind CSS to vanilla CSS, sharing lessons on structuring CSS code for better maintainability.

你好！八年前，我兴奋地写了关于发现 Tailwind 的文章。

那时我真的不知道如何组织我的 CSS 代码，在一堆完全混乱的东西和 Tailwind 之间选择时，我非常高兴地选择了 Tailwind。它帮助我制作了许多小网站！

过去一周左右，我一直在将一些网站从 Tailwind 迁移到更语义化的 HTML 和纯 CSS，这非常有趣且令人兴奋，所以我学到了一些东西！

像往常一样，我不是全职前端开发者，所以我的 CSS 学习多年来都是断断续续发生的。

事实证明 Tailwind 教了我很多

当我开始思考如何组织 CSS 时，一开始我很害怕：我不太擅长组织我的 CSS！但接着我开始阅读关于如何组织 CSS 的博客文章（比如一整套层叠层或我在 2024 年如何写 CSS），然后我意识到几件事：

每个 CSS 代码库都有许多不同的事情在发生（布局！字体！颜色！通用组件！）
为每种事情设置系统或指南非常有用，否则事情会变得混乱
Tailwind 对其中一些事情有系统，而且我已经知道这些系统！也许我可以模仿我喜欢的系统！

例如，Tailwind 有：

一个重置样式表
一个调色板
一个字体比例

我要谈论的系统

我将谈论我的 CSS 代码库的几个方面，以及我目前对每个方面想要强加的规则类型的一些想法。其中一些是从 Tailwind 复制过来的，一些不是。

重置
组件
颜色
字体大小
工具类
基础样式
间距
响应式设计
构建系统

1. 重置

我只是复制了 Tailwind 的"预检样式"，通过进入 tailwind.css 并复制前大约 200 行。

我注意到我随着时间推移已经与 Tailwind 的 CSS 重置建立了关系，例如 Tailwind 在每个元素上设置 box-sizing: border-box（这意味着元素的宽度包括其内边距）：

* { box-sizing: border-box; }

我认为如果没有这些，切换到写 CSS 会是一个真正的调整，我确信 Tailwind 重置中还有许多其他东西（比如 html {line-height: 1.5;}）是我潜意识里习惯的，甚至没有意识到它们的存在。

2. 组件

接下来的这部分是 CSS 的大部分！

这里的想法是按照“组件”来组织 CSS，这在精神上类似于 Vue 或 React 组件。（尽管网站中可能没有任何 JavaScript）

基本上，想法是：

每个“组件”有一个唯一的类
一个组件的 CSS 永远不会覆盖任何其他组件的 CSS
每个组件有自己的 CSS 文件

因此编辑一个组件的 CSS 不会神秘地破坏另一个组件中的任何东西。而且可能我想要更改的 80% 的 CSS 都在各种组件文件中，所以如果我编辑一个 100 行的组件，我只需要考虑那 100 行。这对我来说更容易思考。

例如，这段 HTML 可能是 .zine “组件”：

CSS 看起来像这样，使用嵌套选择器：

.zine {
  ...
  &.horizontal {
    ...
  }
  &.vertical {
    ...
  }
  &:hover {
    ...
  }
}

我没有做任何程序化的事情（比如 web 组件或@scope）来确保组件不会相互干扰，但仅仅有一个约定并尽力而为已经感觉是一个很大的改进。

接下来：在整个站点中保持一些一致性并使这些组件彼此协调的惯例！

3. 颜色

colours.css 有一堆像这样的变量，我可以根据需要使用。颜色真的很难，我不打算在这次重构中重新审视我对颜色的使用，所以我保持原样。

我在这里试图强制执行的唯一指导原则是，站点中使用的所有颜色都列在此文件中。

:root {
  --pink: #fea0c2;
  --pink-light: #F9B9B9;
  --red: #f91a55;
  --orange: rgb(222, 117, 31);
  ...
}

4. 字体大小

我欣赏 Tailwind 的一点是，如果我想设置字体大小，我可以直接想“嗯，我想要文本大一些”，写 text-lg，然后就完成了！如果它不够大，我可能会用 xl 或 2xl 代替。无需尝试记住我是在使用 em、px 还是 rem。

所以我定义了一堆变量，从 Tailwind 取来，像这样：

  --size-xs: 0.75rem;
  --line-height-xs: 1rem;

  --size-sm: 0.875rem;
  --line-height-sm: 1.25rem;

然后，如果我想设置字体大小，我可以这样做。它比 Tailwind 稍微啰嗦一些，但我现在很满意。

h3 {
  font-size: var(--size-lg);
  line-height: var(--line-height-lg);
}

5. 工具类

有些东西像按钮一样出现在许多不同的组件中。我称这些为“工具类”。

我从 Tailwind 复制了一些工具类（比如 .sr-only，用于只应出现在屏幕阅读器用户中的内容）。

这部分很小，我试图谨慎对待这里的更改。

6. 基础样式

“基础”样式是我自己选择的应用于整个站点的样式。我必须保持这一部分非常小，因为我不够自信在整个站点上强制执行许多样式。我现在只对这两个感觉可以，而且我可能会更改

那个：

/* put a 950px column in the middle of each  */
section {
  --inner-width: 950px;
  padding: 3rem max(1rem, (100% - var(--inner-width))/2);
}

a {
  color: var(--orange);
}

我认为对于基础样式，我将从底部向上开始工作——首先从几乎没有基础样式开始，然后随着我识别出想要的共同内容，将一些样式从组件移入基础样式。

7. 间距

我还没有完全确定管理内边距和外边距的方法。不过，我肯定试图比我用 Tailwind 时更有原则，在 Tailwind 中我只是随意地在各处放置内边距和外边距，直到它看起来符合我的要求。

现在我正在努力让外部布局组件尽可能多地负责间距。例如，如果我有一个

，其中有一堆我想要它们之间有空间的子元素，我可以使用这个来均匀地间隔子元素：

section > *+* {
  margin-top: 1rem;
}

一些灵感博客文章：

8. 响应式设计：使用更多网格！

我用 Tailwind 做响应式设计的方式是大量使用媒体查询。Tailwind 有这种 md:text-xl 语法，意思是“在 md 或更大尺寸时应用 text-xl 样式”。

我现在尝试一些非常不同的方法，即制作更灵活的 CSS 网格布局，不需要那么多断点。这很难，但学习网格的可能性非常有趣，而且这是一个我认为用 Tailwind 不可能实现的好例子。

例如，我一直在学习如何使用 auto-fit 来自动在大屏幕上使用 2 列，在小屏幕上使用 1 列，像这样：

  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(min(100%, 400px), max-content));
  justify-content: center;

我还大量使用了grid-template-areas，这是一个我认为你无法用 Tailwind 实现的惊人功能。

一些灵感：

来自 CSS Tricks 的无媒体查询的响应式网格布局

9. 构建系统：esbuild

在开发中，我不需要构建系统：CSS 现在有内置的导入语句，像这样：

@import "reset.css";
@import "typography.css";
@import "colors.css";

以及内置的嵌套选择器，像这样：

.page {
  h2 { ...}
}

如果我想，我可以使用 esbuild 为生产环境打包 CSS 文件。它看起来像这样。

esbuild style.css --bundle --loader:.svg=dataurl  --loader:.woff2=file --outfile=/tmp/out.css

尽管我通常避免使用 CSS 和 JS 构建系统，但我不介意使用 esbuild（我在 2021 年这里写过），因为它是基于 Web 标准的，而且是一个静态的 Go 二进制文件。

为什么迁离 Tailwind？

有几个人问我为什么迁离 Tailwind。一些促成因素是：

自 2018 年以来，Tailwind 变得更依赖构建系统，我认为在不使用构建系统的情况下无法使用较新版本的 Tailwind。所以我多年来一直使用 Tailwind v2。（还有litewind似乎）
一直主张应该与构建系统一起使用 Tailwind，但我从未真正这样做过，所以我在许多项目中都有 2.8MB 的 tailwind.min.css 文件（压缩后 270K），这感觉有点傻。
我比开始使用 Tailwind 时更擅长 CSS 了
最终 Tailwind 是有限的：如果你想在 CSS 中做奇怪的事情，用 Tailwind 不总是可能的。这些限制可能非常有用（这篇文章的很多部分是关于我重新实现 Tailwind 的一些限制！），但此时我希望能够选择和挑选。
我最终得到的网站在同一个项目中混合了纯 CSS 和 Tailwind，维护起来并不有趣
我好奇编写更多语义化 HTML 的感觉如何。

我好奇的 CSS 功能

在做这件事时，我了解了很多我未使用但好奇有朝一日会学习的 CSS 功能：

@layer（来自一整套层叠层）
@scope）（尤其是这个规范中如何在“组件”CSS 设计中使用 @scope 的例子！）
容器查询
子网格

我迁离 Tailwind 的最后一个原因

在这篇文章中，我谈了很多从使用 Tailwind 学到的东西，这都是真的。

但我三年前读了一篇叫Tailwind 和 CSS 的女性气质的文章，它真的留在了我的记忆中。老实说，我可能一开始对 CSS 的态度有点像那篇文章描述的那样：

他们听说它很简单，所以认为它很容易。但当他们尝试使用它时，它不起作用。这一定是语言的错，因为他们知道他们很聪明，而这应该是很容易的。

但在过去 10 年里，我学会了真正喜欢和尊重 CSS 作为一种技术。

所以我几年前决定，我想通过提高 CSS 技能并认真对待它作为技术来回应“CSS 很难”，而不是贬低它。这样做改变了一切：我了解到我的许多挫败感（“居中是不可能的”）在 CSS 中早已得到解决，而且“居中”意味着什么并不总是直接的，它有多种方式是合理的。CSS 很难是因为它在解决一个难题！

我对过去 10-15 年构建的新 CSS 功能印象深刻（其中一些我在本文中讨论过！），它们如何让 CSS 更容易使用，而花时间提高我的 CSS 技能一直是一次非常酷的体验。

那篇文章让我觉得 Tailwind 促进了 CSS 专业知识的贬值，这不是我想参与的事情，即使 Tailwind 对我个人来说是一个有用的工具。尤其是在这个大型语言模型（LLMs）时代，感觉比以往任何时候都更重视人类的专业知识。

另一篇批评 Tailwind 的博客文章影响了我：

经典摇滚、马里奥赛车，以及为什么我们无法就 Tailwind 达成一致

目前就这些！

感谢Melody Starling，她最初设计并编写了 wizardzines.com 的 CSS，网站所有酷炫有趣的东西都归功于 Melody。

另外，我在做这件事时读了很多关于 CSS 的精彩博客文章（来自CSS Tricks、Smashing Magazine 等），我试着在本文中链接其中一些，我真的很感激 CSS 社区中的人们分享他们的实践。

由 mimo-v2.5 模型翻译，花费 9328 tokens

CSS 色板资源链接

Mon, 4 May 2026 00:00:00 +0000

[AI 摘要] 该文分享了作者在告别 Tailwind 后收藏的一系列 CSS 调色板、生成器及颜色工具资源。

前阵子我决定新项目不再使用 Tailwind，转而编写原生 CSS。

但我怀念 Tailwind 的一点是它的调色板（CSS 格式版本在此）。如果我需要浅蓝色，直接使用 blue-100 即可；若不喜欢，可尝试 blue-200 或 blue-50。我对颜色不太在行，因此拥有一套由更擅长颜色的人精心设计的合理调色板，对我来说差别很大。

但我对这些 Tailwind 颜色也有些腻了，于是今天在 Mastodon 上询问还有哪些其他调色板可用。一位朋友说他也想要这些调色板的链接，所以我写了这篇博文，好让我的朋友和其他人都能看到：)

我最喜欢的

我最喜欢的是：

uchū（CSS 文件，常见问题）
flexoki（CSS 文件）
reasonable colours，似乎专注于无障碍访问（CSS 文件）

配色方案生成器

大家还推荐了许多配色方案生成器：

我一直觉得这类生成器太难使用，但或许有一天我的颜色知识会进步到能成功使用配色方案生成器，所以我还是把这些链接放在这里。

更多颜色工具：

colorhexa 提供了一些关于色盲的信息。

`oklch`

CSS 生成颜色展示了一个如何使用 oklch CSS 函数动态生成颜色的示例。

由 mimo-v2.5 模型翻译，花费 2217 tokens

在浏览器中测试Vue组件

Sat, 2 May 2026 00:00:00 +0000

[AI 摘要] 作者分享了在不使用Node.js的情况下，使用QUnit框架在浏览器中直接为Vue组件编写和运行端到端集成测试的实践经验。

大家好！我在这里的长期项目之一是探索如何在不使用Node或其他服务端JavaScript运行时的情况下编写前端JavaScript。

我在前端JavaScript项目中经常遇到的一个问题是不知道如何为它们编写测试。我过去尝试过使用Playwright，但它似乎很慢且笨重，因为总是需要启动这些新的浏览器进程，而且需要一些Node代码来编排测试。

结果就是我干脆不测试我的前端代码，这感觉不太好。通常我也不会经常更新我的项目，所以这个问题不常出现，但如果有更自信地进行更改的能力就好了！因此，一种我喜欢的前端测试方法已经列入我的愿望清单很久了。

想法：直接在浏览器标签页中运行测试

不久前，Alex Chan写了一篇很棒的文章，名为Testing JavaScript without a (third-party) framework，这是对我之前关于如何编写一个运行在浏览器页面中的微型单元测试框架系列文章的回应。

我当时很喜欢这篇文章，但它只谈到了单元测试，而我想为我的Vue组件编写端到端的集成测试，我不知道该怎么做。

所以，当我前几天和Marco交谈时，他说了类似“你知道，你可以直接在浏览器中运行你的Vue组件测试”的话，我想“嘿，我应该再试一次！！！”。

我昨天刚完成这一切，所以肯定还有很多可以改进的地方，但我想在忘记之前写下我对这个过程的一些观察。

这对我来说有点棘手，因为Vue网站通常假设你以某种方式在构建过程中使用Node（有很多“第一步：npm install THING”），而我不想使用Node/Deno等。但结果证明这并不太复杂。

我将要讨论测试的项目是这个我在2023年编写的zine反馈站点。

测试框架：QUnit

我使用了QUnit。它工作得很好，但关于它如何工作，我没什么有趣的话可说，所以我就不说了。我认为Alex的“编写你自己的测试框架”的方法也能行。我遵循了这些说明。

我确实很欣赏QUnit有一个“重新运行测试”按钮，它只会重新运行1个测试。因为我的测试中有大量的网络请求，有一种只运行单个测试的方式使调试测试变得不那么混乱。

第一步：为测试设置组件

我需要做的第一件事是在测试环境中设置我的Vue组件。

我更改了我的主应用程序，将所有的组件放入window._components，大概像这样：

const components = {
  'Feedback': FeedbackComponent,
  ...
}
window._components = components;

然后我能够编写一个mountComponent函数，它基本上与我的正常主应用程序做完全相同的事情（使用我想用的组件渲染一个小模板）。唯一的区别是：

我可以选择性地传递一些额外数据作为它的props。
它将组件挂载到一个临时的、不可见的div上，该div在测试完成后将从DOM中移除。该div被定位在页面外（position: absolute; top: -10000, ...），所以你看不到它。

使用mountComponent函数的样子如下：

const {div} = mountComponent(
  '',
  {feedbacks: [testFeedback]},
);

这是它的代码：

function mountComponent(template, data) {
  const app = Vue.createApp({
    template: template,
    data: () => data,
  })
  for (const [c, v] of Object.entries(window._components)) {
    app.component(c, v);
  }
  const div = document.getElementById('qunit-fixture')
             .appendChild(document.createElement('div'));
  return div;
}

结果是一个div，我可以在其中以编程方式点击、填写表单数据、检查是否出现了正确的内容等。

第二步：添加一些测试夹具数据

因为我正在编写端到端集成测试以确保我的客户端JavaScript与服务器正常工作，所以我需要数据库中有一些测试数据。所以我写了大约25行SQL来在我的数据库中设置一些测试数据，并在开发服务器上添加了一个端点来运行SQL，将测试数据重置到已知状态。

async function reset() {
    return fetch('/api/reset_test_data', {method: "POST"})
}

然后我只需在任何需要测试数据的测试开始时运行await reset()。

我的reset()函数实际上并不总是完全重置所有内容，这有点糟糕，但作为开始是可行的，而且总是可以改进的。

第三步：一个基本测试

这是一个基本测试的样子！基本上我们正在渲染div并确保它包含一些大致正确的数据。

QUnit.test('renders feedback content', async function (assert) {
  const {div} = mountComponent(
    '',
    {feedbacks: [testFeedback]},
  );
  assert.ok(div.textContent.includes('loved this section'));
})

这些都是基本的部分！现在是我在过程中遇到的几个问题：

等待页面的某些部分渲染

我的测试中有很多网络请求，它们需要时间完成，Vue代码也需要时间处理结果并更新DOM。

我想我们很久以前就学到了，在测试中放置随机的sleep()调用并希望时间正确是很慢、很脆弱且极其令人沮丧的，所以我需要一种不同的方式。

据我所知，处理这个问题的通常方式是想办法从DOM中判断是否可以继续。比如“如果这个按钮可见，我们就可以‘’”。

所以我写了一个小waitFor()函数，每20轮询一次条件是否完成。它在2秒后超时。

使用它看起来像这样：

QUnit.test("click item", async function (assert) {
  const {div} = mountComponent(
    '',
    {});
  const item = await waitFor(() => div.querySelector('.feedback-item'));
  item.click();
  // rest of test goes here... 
})

看起来有很多这个概念的实现，它们都比我的更完善。（通过快速谷歌搜索：qunit-wait-for，playwright expect.poll）

弄清楚要等待的正确事情并不简单

在某些情况下，我认为我已经确定了DOM中需要等待的正确内容（“就等这个文本区域出现！”），但结果由于我程序工作方式的一些内部细节，实际上我需要等待稍后其他难以确定的东西。

最终我修改了我的一个组件，在它完成一个重要操作时在DOM中添加一些随机值（比如data-this-thing-is-ready=true），这感觉不太好。

我最好的猜测是，修复这类测试问题的正确方法是进行重构，同时使应用程序对用户更可靠：如果DOM中有一个元素实际上还没有准备好让用户交互，也许我还不应该显示它！

添加一些CSS类来标识事物（但这样对吗？）

我最终向HTML元素添加了一些类，这些类是我需要在测试中找到的，要么是因为我需要点击它们，要么是等待它们出现在DOM中。

我以后可能会改变这种方法——前端测试框架似乎建议避免使用CSS类，而是使用类似getByRole的东西，或者作为最后手段，使用类似data-testid的东西。感觉有一种方法可以让应用程序同时更易于访问且更易于测试。

填写表格很棘手

要填写表单，我不能只设置value，我还需要触发一个事件来告诉Vue元素已经更改。例如，checkbox和textarea需要不同类型的事件。

textarea.value = 'banana banana banana';
textarea.dispatchEvent(new Event('input'));

checkbox.checked = true;
checkbox.dispatchEvent(new Event('change'));

这有点烦人，这让我意识到为什么我可能想要使用某种UI测试库，例如：

Testing Library的填写表单示例看起来与我正在做的事情非常不同。
Vue Test Utils：他们的表单处理部分看起来简化了很多。

测试覆盖率

我想了解我的测试覆盖率是多少，结果Chrome实际上有一个内置的用于JavaScript和CSS的代码覆盖率功能！

我的JavaScript通过esbuild打包成一个名为bundle.js的文件，所以我可以直接查看bundle.js并查看哪些行没有被覆盖。

这个过程有点繁琐：我必须在Chrome开发工具中关闭源映射才能使其工作，而且为了查看覆盖率数据，需要执行一系列不太明显的特定操作。

这太有趣了！

和这些文章一样，我从未真正作为前端或后端开发者工作过（除了为自己工作！），我觉得自己一直在学习如何做最基本的事情。

我真的非常享受这个过程。我的前端项目总是感觉非常脆弱，因为它们没有测试，也许有一天我会有一套我信任的测试套件！

一些我仍在思考的事情：

在写这篇文章时，我发现了这个名为Testing Library的前端测试库，它有很多关于如何编写测试的指南，这些指南与我最初的想法大不相同。我尝试用Testing Library重写所有内容，感觉相当不错，所以我们会看到进展如何。他们提供了一个.umd.js文件，无需Node即可工作。
我不确定我对完全没有命令行运行这些测试的方式感觉如何。也许有一种简单的方法可以主要在浏览器中工作，但如果我想的话，也有在CI中运行它们的方式？

由 mimo-v2.5 模型翻译，花费 6377 tokens

tcpdump和dig手册页示例

Tue, 10 Mar 2026 00:00:00 +0000

[AI 摘要] 作者为tcpdump和dig工具的手册页添加了面向初学者和不常用用户的基础示例。

你好！上个月关于手册页的思考让我最大的收获是：手册页中的示例真的非常有用，因此我着手为我最爱的两个工具的手册页添加（或改进）示例。

以下是成果：

dig手册页（现已包含示例）
tcpdump手册页示例（这是在原有示例基础上的更新）

目标：包含最基础的示例

这里的目标纯粹是提供关于如何使用该工具的最基础示例，面向那些不常使用tcpdump或dig（或从未使用过！）且不记得其工作原理的人。

到目前为止，提出“我想为这个工具的初学者和不常使用的用户写一个示例章节”这个说法一直非常奏效。它易于解释，根据我听到的用户对手册页的需求，我认为这很合理，维护者们似乎也认为它很有说服力。

感谢Denis Ovsienko、Guy Harris、Ondřej Surý以及所有审阅文档更改的人，这是一次愉快的经历，激励我继续在手册页上做更多工作。

为何要改进手册页？

我现在有兴趣参与工具官方文档的工作，因为：

手册页实际上可以达到接近100%的准确性！经过审查流程以确保信息真实无误具有很大价值。
即使是关于“tcpdump最常用的标志是什么”这样的基本问题，维护者通常也了解一些我不知道的实用功能！例如，在处理这些tcpdump示例时我了解到，使用tcpdump -w out.pcap将数据包保存到文件时，加上-v参数来打印已捕获数据包数量的实时摘要非常有用。这非常有用，我不知道，而且我认为我自己可能永远不会注意到它。

说实话，我总觉得文档会很难读，所以我通常会跳过它，转而去读一篇博客文章、Stack Overflow评论或者问朋友，所以现在这个位置对我来说有点奇怪。但现在我感到乐观，也许文档不一定非得糟糕？也许它可以像阅读一篇非常棒的博客文章一样好，同时又确保了正确性？我最近一直在使用Django的文档，它真的很好！我们拭目以待。

关于避免编写手册页语言

tcpdump项目工具的手册页是用roff语言编写的，这有点难用，我真的不想学它。

我的解决方法是编写一个非常基本的markdown-to-roff脚本来将Markdown转换为roff，遵循手册页已有的类似约定。也许我可以直接用pandoc，但它生成的输出看起来差别很大，所以我觉得写自己的脚本可能更好。谁知道呢。

能够直接使用现有Markdown库来解析Markdown AST，然后实现我自己的代码生成方法来以在这种情境下似乎合理的方式格式化内容，我觉得这很酷。

手册页很复杂

受了解mandoc项目（BSD系统及一些Linux系统，我想Mac OS也用它来格式化手册页）的启发，我深入研究了roff的历史、它自70年代以来的发展以及现在是谁在维护它。不过今天我就不多说了，也许改天再说。

总的来说，BSD和Linux在文档工作方式上似乎存在技术和文化上的分歧，我仍然没有真正理解，但我一直对BSD世界正在发生的事情感到好奇。

评论区在此。

由 mimo-v2.5 模型翻译，花费 2717 tokens

关于改进手册页的笔记

Wed, 18 Feb 2026 00:00:00 +0000

[AI 摘要] 本文探讨了改进命令行工具手册页的各种方法，包括添加选项摘要、分类组织、速查表和示例，以提升可用性。

大家好！去年花了些时间研究 Git 的手册页后，我开始更深入地思考什么才是好的手册页。

我曾为许多工具（tcpdump、git、dig 等）编写速查表，这些工具的手册页是其主要文档。因为我经常发现手册页难以快速找到所需信息。

最近我在想——手册页本身能否包含出色的速查表？什么能让手册页更易用？我的思考还处于早期阶段，但想先记录下一些快速笔记。

我在 Mastodon 上询问了大家最喜欢的手册页，以下是我从那些手册页中看到的一些有趣示例。

选项摘要

如果你读过很多手册页，可能在SYNOPSIS部分见过类似这样的内容：当你列出几乎所有字母时，就显得很难读

ls [-@ABCFGHILOPRSTUWabcdefghiklmnopqrstuvwxy1%,]

grep [-abcdDEFGHhIiJLlMmnOopqRSsUVvwXxZz]

rsync 手册页有一个我从未见过的解决方案：它将 SYNOPSIS 保持得非常简洁，像这样：

 Local:
     rsync [OPTION...] SRC... [DEST]

然后有一个"选项摘要"部分，每个选项用一行总结，如下：

--verbose, -v            increase verbosity
--info=FLAGS             fine-grained informational verbosity
--debug=FLAGS            fine-grained debug verbosity
--stderr=e|a|c           change stderr output mode (default: errors)
--quiet, -q              suppress non-error messages
--no-motd                suppress daemon-mode MOTD

之后还有通常的 OPTIONS 部分，对每个选项进行完整描述。

按类别组织的选项部分

strace 手册页按类别（如"通用"、"启动"、"跟踪"、"过滤"和"输出格式"）组织其选项，而不是按字母顺序。

作为实验，我尝试将grep手册页改造成一个按类别分组的"选项摘要"部分，你可以在这里查看结果。我不确定自己对结果的看法，但这是一个有趣的练习。写的时候我在想，我总记不住grep的-l选项名称。在手册页中找到它似乎要花很长时间，我一直在思考什么样的结构能让我更容易找到。也许是类别划分？

速查表

有几个人向我推荐了 Perl 手册页系列（perlfunc、perlre等），我注意到的一件事是man perlcheat，它有像这样的速查表部分：

 SYNTAX
 foreach (LIST) { }     for (a;b;c) { }
 while   (e) { }        until (e)   { }
 if      (e) { } elsif (e) { } else { }
 unless  (e) { } elsif (e) { } else { }
 given   (e) { when (e) {} default {} }

我觉得这很酷，这让我想知道是否有其他方法可以在手册页中编写简洁的80字符宽 ASCII 速查表。

示例非常受欢迎

一个常见的评论是"我喜欢任何有示例的手册页"。有人提到了 OpenBSD 手册页，openbsd tail手册页中有我最后使用 tail 的两种方式的示例。

我最常在手册页末尾看到 EXAMPLES 部分，但有些手册页（比如前面的rsync 手册页）以示例开头。在处理git-add和git rebase手册页时，我在开头放了一个简短示例。

目录和部分之间的链接

这不是手册页本身的特性，但终端中的一个问题是很难知道手册页包含哪些部分。

在处理 Git 手册页时，Marie 和我做的一件事是在 Git 站点托管的 HTML 版本手册页侧边栏中添加了目录。

我也想在某个时候为 Git 手册页的 HTML 版本添加更多超链接，这样你就可以点击"不兼容选项"直接跳转到该部分。在 Git 项目中添加这样的链接非常容易，因为 Git 的手册页是用 AsciiDoc 生成的。

我认为添加目录和内部超链接是一种不错的折中方案，可以改善手册页格式（至少在 HTML 版本中），而无需维护完全不同的文档形式。不过，要实现这一点，你需要像 Git 的 AsciiDoc 系统那样的工具链。

如果有某种通用系统能轻松查找手册页中的特定选项（"-a 是做什么的？"）就太好了。我所知的最佳技巧是使用手册页分页器搜索类似^ *-a的内容，但我总是忘记这样做，而是会翻阅手册页中每个-a的实例，直到找到所需内容。

每个选项的示例

curl 手册页为每个选项提供了示例，HTML 版本中还有目录，可以更方便地跳转到感兴趣的选项。

例如，--cert的示例很容易让你看到可能还需要传递--key选项，像这样：

  curl --cert certfile --key keyfile https://example.com

他们的实现方式是每个选项有一个文件，文件中包含"示例"字段。

在表格中格式化数据

很多人说man ascii是他们最喜欢的手册页，它看起来像这样：

 Oct   Dec   Hex   Char                     
 ───────────────────────────────────────────
 000   0     00    NUL '\0' (null character)
 001   1     01    SOH (start of heading)   
 002   2     02    STX (start of text)      
 003   3     03    ETX (end of text)        
 004   4     04    EOT (end of transmission)
 005   5     05    ENQ (enquiry)            
 006   6     06    ACK (acknowledge)        
 007   7     07    BEL '\a' (bell)          
 010   8     08    BS  '\b' (backspace)     
 011   9     09    HT  '\t' (horizontal tab)
 012   10    0A    LF  '\n' (new line)

显然man ascii是一个不寻常的手册页，但我认为这个手册页酷的地方（除了拥有 ASCII 参考总是很有用之外）是表格格式使扫描信息非常容易。这让我想知道是否有更多机会在手册页中以"表格"形式显示信息，使其更易于浏览。

GNU 的方法

当我谈论手册页时，经常提到 GNU coreutils 手册页（例如man tail）没有示例，而 OpenBSD 手册页有示例。

我不打算过多讨论这个，因为它似乎是一个相当政治性的话题，我肯定无法在这里公正地处理，但以下是我认为真实的一些事情：

GNU 项目更倾向于在"info"手册而非手册页中维护文档。此页面表示"手册页不再维护"。
有三种方式阅读"info"手册：HTML 版本、在 Emacs 中使用，或使用独立的info工具。我听说一些 Emacs 用户喜欢 Emacs 的 info 浏览器。我想我从未与任何使用独立info工具的人交谈过。
tail 的 info 手册条目链接在手册页底部，并且确实有示例
FSF 曾销售 GNU 软件手册的印刷书籍（也许他们现在有时还在卖？）

达到一定复杂度后，手册页会变得非常难以导航：虽然我从未使用过 coreutils 的 info 手册，也可能不会使用，但我几乎肯定会更喜欢使用GNU Bash 参考手册或GNU C 库参考手册的 HTML 文档，而不是通过手册页。

一些与手册页相关的工具

以下是我认为有趣的一些工具：

fish shell附带一个Python 脚本，可以从手册页自动生成 Tab 补全
tldr.sh是一个社区维护的示例数据库，例如你可以运行tldr grep。很多人告诉我他们觉得它很有用。
Dash Mac 文档浏览器中有一个不错的手册页查看器。我仍然使用终端手册页查看器，但我喜欢它包含目录，看起来像这样：

思考受限格式很有趣

手册页是一种受限格式，思考在如此有限的格式化选项下能做什么很有趣。

尽管我非常喜欢写作，但我一直有从不阅读文档的坏习惯，所以对我来说思考手册页中哪些内容真正有用有点困难，我不确定这篇帖子中的大多数内容是否会改善我的体验。（除了示例，我非常喜欢示例）

因此，我很想听听你们认为哪些手册页设计良好以及喜欢它们什么，评论区在这里。

由 mimo-v2.5 模型翻译，花费 6651 tokens

开始使用 Django 的一些笔记

Tue, 27 Jan 2026 00:00:00 +0000

[AI 摘要] 这是一篇关于作者初次学习并使用 Django Web 框架的个人体验笔记，分享了其相比 Rails 更显式、内置管理界面、ORM 及迁移系统、良好文档和内置功能等优点。

你好！我最喜欢的事情之一，就是开始学习一门我从未尝试过但已经存在 20 多年的“老旧无聊技术”。当发现我将来可能遇到的每一个问题都已经被解决过上千次，我可以轻松搞定一切时，感觉真的很好。

我很久以前就觉得学习像 Rails、Django 或 Laravel 这样流行的 Web 框架会很酷，但一直没能真正付诸行动。不过几个月前，我开始学习 Django 来制作一个网站，到目前为止我很喜欢它，这里有一些简短的笔记！

比 Rails 魔法少

我在 2020 年花了一些时间尝试学习 Rails，虽然它很酷，而且我真的很想喜欢 Rails（Ruby 社区很棒！），但我发现如果我将一个 Rails 项目闲置几个月，当我回来时，就很难记起如何进行任何操作，因为（例如）如果在你的 routes.rb 文件中写着 resources :topics，这本身并不能告诉你 topics 路由是在哪里配置的，你需要记住或查阅相关约定。

能够将一个项目搁置数月甚至数年，然后回来继续工作，对我来说非常重要（我所有的项目都是这样运作的！），而 Django 对我来说感觉更容易，因为事物更加显式。

在我的小型 Django 项目中，感觉我只需要关注 5 个主要文件（除了设置文件）：urls.py、models.py、views.py、admin.py 和 tests.py，如果我想知道其他东西（比如 HTML 模板）在哪里，它通常会从其中一个文件中被显式引用。

一个内置的管理后台

对于这个项目，我想要有一个管理界面来手动编辑或查看数据库中的某些数据。Django 有一个非常好的内置管理界面，我只需少量代码就能对其进行自定义。

例如，这是我其中一个管理类的部分内容，它设置了“列表”视图中要显示的字段、用于搜索的字段以及默认的排序方式。

@admin.register(Zine)
class ZineAdmin(admin.ModelAdmin):
    list_display = ["name", "publication_date", "free", "slug", "image_preview"]
    search_fields = ["name", "slug"]
    readonly_fields = ["image_preview"]
    ordering = ["-publication_date"]

拥有一个 ORM 很有趣

过去我的态度是“ORM？谁需要它们？我可以自己写 SQL 查询！”。然而，到目前为止我一直很享受 Django 的 ORM，我觉得 Django 用 __ 来表示 JOIN 连接的方式很酷，就像这样：

Zine.objects
    .exclude(product__order__email_hash=email_hash)

这个查询涉及 5 张表：zines、zine_products、products、order_products 和 orders。为了使其工作，我只需告诉 Django 存在一个关联“订单”和“产品”的 ManyToManyField，以及另一个关联“杂志”和“产品”的 ManyToManyField，这样它就知道如何连接 zines、orders、products 表了。

我确实可以手写那个查询，但编写 product__order__email_hash 打字量少得多，感觉更容易阅读，而且老实说，我想我要花一点时间才能弄清楚如何构造这个查询（它需要做的事情比仅仅连接这些表多一些）。

我完全不担心 ORM 生成的查询的性能，所以我目前对 ORM 相当兴奋，尽管我肯定最终会发现一些令人沮丧的地方。

自动迁移！

ORM 的另一个优点是迁移！

如果我在 models.py 中添加、删除或更改一个字段，Django 会自动生成一个迁移脚本，例如 migrations/0006_delete_imageblob.py。

我想我也可以编辑这些脚本，但到目前为止，我只是直接运行生成的脚本而没有做任何更改，效果一直很好。这感觉真的像魔法一样。

我意识到能够轻松进行迁移对我现在很重要，因为我在弄清楚数据模型如何工作时，会频繁地更改它。

我喜欢文档

我过去有个坏习惯，就是从不阅读文档，但我真的很喜欢到目前为止读过的 Django 文档的部分内容。这并非偶然：Jacob Kaplan-Moss 有一个 2011 年 PyCon 的演讲，讲述了 Django 的文档文化。

例如，模型入门文档列出了在使用 ORM 时你可能需要设置的最重要的常见字段。

使用 sqlite

在尝试操作 Postgres 却搞不懂发生了什么之后有过糟糕体验，我决定改用 SQLite 来运行我所有的小型网站。效果好多了，我特别喜欢只需要执行 VACUUM INTO 然后复制生成的单个文件就能进行备份。

我一直在遵循这些指南在生产环境中将 SQLite 与 Django 一起使用。

我认为这应该没问题，因为我预计这个网站每天最多只有几百次写入，比 Mess with DNS 少得多，后者有更多的写入量并且一直运行良好（尽管写入分布在三个不同的 SQLite 数据库上）。

内置的电子邮件（以及更多）

Django 似乎非常“开箱即用”，我喜欢这点——如果我需要 CSRF 保护、Content-Security-Policy，或者想发送电子邮件，这些功能都在里面！

例如，我想在开发模式下将 Django 发送的电子邮件保存到文件中（这样就不会向真实的人发送真实邮件），这只需要一点点配置。

我在 settings/dev.py 中放入了这个：

EMAIL_BACKEND = "django.core.mail.backends.filebased.EmailBackend"
EMAIL_FILE_PATH = BASE_DIR / "emails"

然后在 settings/production.py 中这样设置生产环境的电子邮件：

EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = "smtp.whatever.com"
EMAIL_PORT = 587
EMAIL_USE_TLS = True
EMAIL_HOST_USER = "xxxx"
EMAIL_HOST_PASSWORD = os.getenv('EMAIL_API_KEY')

这让我觉得，如果我想要其他一些基本的网站功能，很可能在 Django 中已经内置了简便的实现方式。

设置文件仍然感觉很多

我仍然对 settings.py 文件感到有点望而生畏：Django 的设置系统通过在一个文件中设置一堆全局变量来工作，我有点担心……如果我打错了其中一个变量的名字怎么办？我怎么知道？如果我输入 WSGI_APPLICATOIN = "config.wsgi.application" 而不是 WSGI_APPLICATION 怎么办？

我想我已经习惯了有 Python 语言服务器告诉我是否有拼写错误，所以现在当我无法依赖语言服务器支持时，感觉有点无所适从。

这就是目前的所有内容了！

我以前从未真正成功地为一个项目使用过真正的 Web 框架（现在我几乎所有的网站要么是单个 Go 二进制文件，要么是静态网站），所以我很想看看接下来会怎样！

我仍然有很多东西需要学习，我还没有真正深入了解 Django 的表单验证工具或认证系统。

感谢 Marco Rogers 说服我给 ORM 一个机会。

（我们仍在尝试 Mastodon 评论系统！这是 Mastodon 上的评论！告诉我你最喜欢的 Django 功能！）

由 mimo-v2.5 模型翻译，花费 4994 tokens

Git 的数据模型（及其他文档更新）

Thu, 8 Jan 2026 00:00:00 +0000

[AI 摘要] 作者通过撰写新数据模型文档和根据测试读者反馈改进手册页，为 Git 文档做出了贡献。

大家好！去年秋天，我决定花一些时间来改进 Git 的文档。我早就想为开源文档做贡献了——通常如果我觉得某个软件的文档可以改进，我会写一篇博客文章或一份 zine 之类的。但这次我转念一想：我能不能直接去改进官方文档呢？

于是 Marie 和我对 Git 文档做了一些改动！

Git 的一个数据模型

在参与文档工作一段时间后，我们注意到 Git 在其文档中频繁使用“对象”、“引用”或“索引”等术语，却没有很好地解释这些术语的含义，或者它们如何与“提交”和“分支”等其他核心概念相关联。因此，我们撰写了一份新的“数据模型”文档！

你可以在此处阅读该数据模型（目前版本）。我估计在某个时候（下一次发布之后？），它也会出现在 Git 网站上。

我对此感到很兴奋，因为理解 Git 如何组织其提交和分支数据，多年来真正帮助我理解了 Git 的工作原理。我认为有一份简短（1600 词！）且准确的数据模型版本是很重要的。

“准确”这部分证明并非易事：我知道 Git 数据模型如何工作的基础知识，但在审查过程中，我学到了一些新的细节，并不得不做出相当多的修改（例如，暂存区如何存储合并冲突）。

更新 `git push`、`git pull` 及更多内容

我还致力于更新一些 Git 核心手册页的介绍部分。我很快意识到，“仅凭我的最佳判断去尝试改进”是行不通的：为什么维护者应该相信我的版本更好？

在讨论开源文档改动时，我经常看到一个问题：两位软件的专家用户会争论某个解释是否清晰（“我觉得 X 是个好方法！” “不，我觉得 Y 更好！”）。

我认为这样做效率不高（软件的专家用户往往不擅长判断某个解释对非专家是否清晰），因此我需要找到一种方法，能够以更基于证据的方式找出手册页中的问题。

让测试读者识别问题

我在 Mastodon 上邀请测试读者阅读当前版本的文档，并告诉我他们觉得困惑的地方或他们有什么问题。大约 80 位测试读者留下了评论，我学到了很多！

人们留下了大量极好的反馈，例如：

他们不理解的术语（什么是路径规范？“引用”是什么意思？“上游”在 Git 中是否有特定含义？）
特定的、令人困惑的句子
建议添加的内容（“我经常做 X，我觉得这里应该包含进去”）
不一致之处（“这里暗示 X 是默认值，但别处暗示 Y 是默认值”）

大多数测试读者使用 Git 至少有 5-10 年，我认为这效果很好——如果一群经常使用 Git 超过 5 年的测试读者都觉得某个句子或术语无法理解，那就很容易论证文档应该被更新得更清晰。

我觉得这种“让软件用户对现有文档发表评论，然后修复他们发现的问题”的模式效果非常好，我期待将来可能再次尝试。

手册页的改动

我们最终更新了以下 4 个手册页：

git add (改动前, 改动后)
git checkout (改动前, 改动后)
git push (改动前, 改动后)
git pull (改动前, 改动后)

其中 git push 和 git pull 的改动对我来说是最有趣的：除了更新这些页面的介绍部分，我们最终还撰写了：

一个描述“上游分支”这一术语含义的部分（之前并未真正解释）
一个清理后的关于“推送引用规范”是什么的描述

进行这些改动真的让我体会到维护开源文档是多么费力的一件事：要写出既清晰又正确的内容并不容易，有时我们不得不做出妥协，例如句子“git push 可能会失败，如果你还没有为当前分支设置上游，这取决于 push.default 的设置。”有点模糊，但“取决于”具体意味着什么其实非常复杂，理清这一点是一个很大的工程。

关于为 Git 贡献代码的流程

我花了一段时间才理解 Git 的开发流程。我不打算在此详细描述（那可能是另一整篇博文了！），但简要说明几点：

Git 有一个 Discord 服务器，其中有一个“我的第一次贡献”频道，提供入门帮助。我发现 Discord 上的人非常友好。
我使用了 GitGitGadget 来进行所有贡献。这意味着我可以提交一个 GitHub 拉取请求（我熟悉的工作流程），GitGitGadget 会将我的 PR 转换为 Git 开发者使用的系统（带附件补丁的电子邮件）。GitGitGadget 工作得很好，我非常感激不必学习如何通过电子邮件使用 Git 发送补丁。
其他情况下，我使用我的常规电子邮件客户端（Fastmail 的 Web 界面）回复邮件，并按照邮件列表规范将文本限制在每行 80 个字符内。

我还发现 lore.kernel.org 上的邮件列表存档很难浏览，所以我匆忙拼凑了我自己的 Git 列表查看器，以便更轻松地阅读冗长的邮件列表讨论。

许多人帮助我了解贡献流程并审查这些改动：感谢 Emily Shaffer、Johannes Schindelin（GitGitGadget 的作者）、Patrick Steinhardt、Ben Knoble、Junio Hamano 等人。

（我正在实验在 Mastodon 上使用评论功能，你可以在此查看评论）

由 mimo-v2.5 模型翻译，花费 4795 tokens

从vim切换到Helix的笔记

Fri, 10 Oct 2025 00:00:00 +0000

[AI 摘要] 本文作者分享了从 Vim 切换到 Helix 编辑器三个月的体验，包括选择原因、与 Vim 的对比以及遇到的优缺点。

你好！今年夏天早些时候，我和一位朋友聊到我有多喜欢使用 fish shell，以及我有多喜欢它不需要我进行配置。他们说对 Helix 文本编辑器也有同样的感觉，所以我决定尝试一下。

我已经使用它三个月了，以下是一些笔记。

为什么选择 Helix：语言服务器

我想尝试 Helix 的动机在于，我一直在尝试设置一个可用的语言服务器环境（这样我就能做诸如“跳转到定义”之类的事情），而在 Vim 或 Neovim 中搭建一个感觉良好的环境实在费时费力。

在使用 Vim/Neovim 20 年后，我尝试过“从零开始构建自己的自定义配置”和“使用别人预先构建的配置系统”，尽管我热爱 Vim，但想到一切都能直接工作而无需在配置上花费精力，我还是感到兴奋。

Helix 内置了语言服务器支持，能在任何语言中轻松执行诸如“重命名此符号”之类的操作，感觉很棒。

搜索功能很棒

Helix 中我最喜欢的一点是它的搜索功能！如果我在整个代码库中搜索某个字符串，它会让我滚动浏览可能的匹配文件，并看到匹配行的完整上下文，就像这样：

作为对比，这里是我之前一直在用的 Vim ripgrep 插件的样子：

它没有显示该行周围的其他上下文。

快速参考提示很好

我喜欢 Helix 的一点是，当我按下 g 键时，会弹出一个小帮助菜单，告诉我可以跳转到哪里。我非常欣赏这一点，因为我不常使用“跳转到定义”或“跳转到引用”功能，经常忘记相应的键盘快捷键。

一些 Vim 到 Helix 的键位映射

Helix 没有像 ma、'a 这样的标记功能，我一直在使用 Ctrl+O 和 Ctrl+I 来返回（或前进到）上一个光标位置。
我认为 Helix 也有宏功能，但在所有我以前会使用宏的情况下，我一直在使用多光标。我非常喜欢多光标，胜过总是编写宏。如果我想在文档中批量更改某些内容，我的工作流程是：按 %（全选），然后按 s（使用正则表达式）选择我想要更改的内容，然后就可以直接进行所需的编辑。
Helix 没有 Neovim 风格的标签页，取而代之的是一个不错的缓冲区切换器（b），我可以用它来切换到我想要的缓冲区。这里有一个实现 Neovim 风格标签页的拉取请求。还有一个设置 bufferline="multiple"，配合 gp、gn 进行上/下一个“标签页”，以及用 :bc 关闭“标签页”，可以起到类似标签页的作用。

一些令我烦恼的 Helix 问题

以下是我目前在使用 Helix 时遇到的所有令我烦恼的地方。

我非常喜欢 Helix 的 :reflow 功能，但它处理列表的方式不如 Vim 的 gq 重排文本那样好。（GitHub issue）
如果我在创建 Markdown 列表，在列表项末尾按“回车”不会延续列表。对于项目符号列表，有一个部分解决方案，但我不知道编号列表的解决方法。

目前还没有持久化撤销：在 Vim 中，我可以使用撤销文件，这样即使退出后也能撤销更改。Helix 还没有这个功能。（GitHub PR）

Helix 不会在磁盘上的文件更改后自动重新加载，我必须运行 :reload-all（:ra）来手动重新加载。这不是什么大问题。
有时它会崩溃，大概每周一次。我想可能与这个问题有关。

崩溃信息大致如下：

thread 'main' panicked at helix-core/src/transaction.rs:499:9:
Positions [(2959, AfterSticky), (2959, AfterSticky)] are out of range for changeset len 2945!
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

“Markdown 列表”和文本重排的问题经常困扰我，因为我花很多时间编辑 Markdown 列表，但我仍然继续使用 Helix，所以我想它们还不至于让我特别生气。

切换比想象中容易

我曾担心重新学习 20 年的 Vim 肌肉记忆会非常困难。

结果比预期要容易。我在一次度假时开始使用 Helix，进行一个副业的小型编码项目，一两周后，那种迷失方向的感觉就消失了。我想在 Vim 和 Helix 之间来回切换可能会比较困难，但我最近不需要使用 Vim，所以我不知道这是否对我来说会成为问题。

第一次尝试 Helix 时，我试图强制它使用更接近 Vim 的键位绑定，但这对我不管用。直接学习“Helix 的方式”要容易得多。

仍然有些事情让我困惑：例如，Vim 中的 w 和 Helix 中的 w 对“单词”的定义不同（Helix 的包含单词后的空格，Vim 的不包含）。

使用基于终端的文本编辑器

多年来，我主要使用 GUI 版本的 Vim/Neovim，所以切换到在终端中实际使用编辑器需要一些调整。

我最终决定：

每个项目都有自己独立的终端窗口，该窗口中的所有标签页（主要）共享同一个工作目录。
我把 Helix 标签页设为终端窗口中的第一个标签页。

效果相当好，我可能实际上比我之前的工作流程更喜欢这种方式。

我的配置

我很欣赏我的配置非常简单，相比之下，我的 Neovim 配置有数百行。它主要只有 4 个键盘快捷键。

theme = "solarized_light"
[editor]
# 与系统剪贴板同步
default-yank-register = "+"

[keys.normal]
# 我不喜欢默认的 "切换注释" 快捷键是 Ctrl+C
"#" = "toggle_comments"

# 我不想学习另一种方式去行首/行尾
# 所以我重新映射了 ^ 和 $
"^" = "goto_first_nonwhitespace"
"$" = "goto_line_end"

[keys.select]
"^" = "goto_first_nonwhitespace"
"$" = "goto_line_end"

[keys.normal.space]
# 我经常写文字，需要不断重排，
# 思念 Vim 的 `gq` 快捷键
l = ":reflow"

还有一个单独的 languages.toml 配置文件，我可以在其中设置一些语言偏好，例如关闭自动格式化。例如，我的 Python 配置如下：

[[language]]
name = "python"
formatter = { command = "black", args = ["--stdin-filename", "%{buffer_name}", "-"] }
language-servers = ["pyright"]
auto-format = false

我们拭目以待

三个月并不算长，我有可能在某个时候决定回到 Vim。例如，我之前写过一篇关于切换到 Nix 的文章，但大约 8 个月后，我又切换回了 Homebrew（不过我仍然使用 NixOS 管理一个小型服务器，并且对此仍然满意）。

由 mimo-v2.5 模型翻译，花费 5139 tokens

新Zine：终端的神秘规则

Thu, 26 Jun 2025 00:00:00 +0000

[AI 摘要] 本文介绍了新Zine《终端的神秘规则》的发布，解释了终端内部工作原理和写作背景。

你好！经过数月深入撰写关于终端的博客文章，我于周二发布了一本新Zine，名为《终端的神秘规则》！

你可以在这里以12美元购买：https://wizardzines.com/zines/terminal，或者在此获取我所有Zine的15本套装。

这是封面：

为什么是终端？

我已经使用终端20年了，但尽管我对终端非常自信，我总是对它有一点不安的感觉。通常事情运行顺利，但有时出问题时，感觉调查起来不可能，或者至少像会引发一大堆问题。

所以我开始尝试列出我在终端中遇到的一些奇怪问题，并意识到终端有许多微小的不一致性，比如：

有时你可以使用方向键移动，但有时按下方向键只会打印^[[D
有时你可以用鼠标选择文本，但有时不能
有时运行命令时会被保存到历史记录中，有时则不会
有些shell允许你用上箭头查看之前的命令，有些则不允许

如果你每天使用终端10或20年，即使你不完全理解为什么这些事情会发生，你可能也会对它们建立直觉。

但对它们有直觉并不等同于理解它们为什么发生。在写这本Zine时，我实际上做了很多工作来弄清楚终端中正在发生什么，以便能够讨论如何推理它。

规则没有被写在任何地方

事实证明，终端工作方式的“规则”（如何编辑你输入的命令？如何退出程序？如何修复你的颜色？）极难完全理解，因为“终端”实际上由许多不同的软件部分组成（你的终端模拟器、操作系统、shell、核心工具如grep，以及你安装的每个其他随机终端程序），这些部分由不同的人编写，对事物应如何工作有不同的想法。

所以我想写点东西来解释：

终端的4个部分（你的shell、终端模拟器、程序和TTY驱动程序）如何协同工作
一些核心约定，关于你可以期望终端中的事情如何工作
许多使用终端程序的技巧和窍门

这本Zine解释了终端内部最有用的部分

终端内部是一团糟。很多部分就是这样，因为有人在80年代做了决定，现在无法更改，老实说，我认为学习终端内部的所有内容并不值得。

但有些部分并不太难理解，并且确实可以让你在终端中的体验更好，比如：

如果你理解你的shell负责什么，你可以配置你的shell（或使用不同的shell！）来更轻松地访问历史记录、获得出色的选项卡补全等
如果你理解转义码，当cat一个二进制文件到标准输出搞乱你的终端时，你就不会那么害怕，你可以直接输入reset然后继续
如果你理解颜色如何工作，你可以摆脱终端中糟糕的颜色对比度，从而真正阅读文本

我写这本Zine时学到了惊人的东西

当我写《Git如何工作》时，我以为我了解Git的工作原理，我是对的。但终端是不同的。尽管我对终端完全自信，并且每天使用它20年，我对终端的工作原理有很多误解，而且（除非你是tmux之类的作者）我认为你很有可能也有。

一些我学到的实际上对我有用的事情：

我更好地理解了终端的结构，所以当奇怪的终端事情发生在我身上时，我更有信心调试（我甚至能够对fish提出一个小改进！）。准确找出是哪个软件导致终端中发生奇怪的事情仍然不容易，但我现在好多了。
你可以编写一个shell脚本通过SSH复制到你的剪贴板
reset在底层如何工作（它相当于执行stty sane; sleep 1; tput reset）——基本上我了解到我不需要担心记住stty sane或tput reset，我只需要运行reset即可
如何查看程序打印出的不可见转义码（运行unbuffer program > out; less out）
为什么我Mac上的内置REPL如sqlite3如此恼人（它们使用libedit而不是readline）

我在此过程中写的博客文章

像往常一样，我写了很多关于各种副任务的博客文章：

如何将目录添加到你的PATH
终端问题遵循的“规则”
为什么管道有时会“卡住”：缓冲
一些终端挫折
我终端中的ASCII控制字符关于“Ctrl+A、Ctrl+B、Ctrl+C等是什么情况？”
在终端中输入文本很复杂
获取“现代”终端设置涉及什么？
使用shell作业控制的原因
ANSI转义码标准，这实际上是我试图弄清楚我认为terminfo数据库在今天是否服务良好

帮助这本Zine的人

很久以前，我大多自己写Zine，但随着每个项目，我得到越来越多的帮助。我从九月到六月的每个工作日都与Marie Claire LeBlanc Flanagan会面，一起做这本Zine。

封面由Vladimir Kašiković设计，Lesley Trites做了文字编辑，Simon Tatham（PuTTY的作者）做了技术审查，我们的运营经理Lee做了转录以及其他无数事情，Jesse Luehrs（他是我认识的极少数真正理解终端神秘内部工作原理的人之一）与我进行了许多极其有用的对话，关于终端中发生的事情。

获取这本Zine

以下是再次获取这本Zine的链接：

获取《终端的神秘规则》
获取我所有Zine的15本套装。

像往常一样，你可以获取PDF版本在家打印，或者获取打印版本寄送到你家。唯一的注意事项是打印订单将在八月发货——我需要等待订单进来，以便在发送给印刷商之前了解应该印刷多少份。

由 mimo-v2.5 模型翻译，花费 5759 tokens

使用 `make` 编译 C 程序（面向非 C 程序员）

Tue, 10 Jun 2025 00:00:00 +0000

[AI 摘要] 这篇文章介绍非 C 程序员如何使用 `make` 工具来编译 C 程序，并提供了实用步骤和技巧。

我从来不是一名 C 程序员，但偶尔需要从源代码编译 C/C++ 程序。这对我来说一直有点困难：很长一段时间，我的方法基本上是“安装依赖项，运行 make，如果不行，就试着找到别人编译好的二进制文件，或者放弃”。

“希望别人已经编译好”在我使用 Linux 时效果不错，但自从两年前我开始使用 Mac 后，我遇到更多必须自己编译程序的情况。

所以，让我们来谈谈编译 C 程序可能需要做什么！我将使用几个我编译过的 C 程序示例，并讨论一些可能出错的地方。以下是三个我们将要讨论编译的程序：

paperjam
sqlite
qf（一个分页器，可以使用 rg -n THING | qf 从搜索结果快速打开文件）

步骤 1：安装 C 编译器

这很简单：在 Ubuntu 系统上，如果我没有 C 编译器，我会用以下命令安装一个：

sudo apt-get install build-essential

这会安装 gcc、g++ 和 make。在 Mac 上的情况更复杂，但大致是“安装 Xcode 命令行工具”。

步骤 2：安装程序的依赖项

与一些较新的编程语言不同，C 没有依赖管理器。因此，如果程序有任何依赖项，你需要自己寻找它们。幸运的是，正因为如此，C 程序员通常保持依赖项非常 minimal，并且依赖项通常可以在你使用的任何包管理器中找到。

几乎总有一个部分在 README 中解释如何获取依赖项，例如在 paperjam 的 README 中，它说：

要编译 PaperJam，你需要 libqpdf 和 libpaper 库的头文件（通常作为 libqpdf-dev 和 libpaper-dev 包提供）。

你可能需要 a2x（来自 AsciiDoc）来构建手册页。

所以在基于 Debian 的系统上，你可以这样安装依赖项。

sudo apt install -y libqpdf-dev libpaper-dev

如果 README 给出了包的名称（如 libqpdf-dev），我基本上总是假设它指的是“在基于 Debian 的 Linux 发行版中”：如果你在 Mac 上，brew install libqpdf-dev 将不起作用。我仍然没有完全掌握在 Mac 上开发的技巧，所以我还没有太多提示。我想在这种情况下，如果你使用 Homebrew，可能是 brew install qpdf。

步骤 3：运行 `./configure`（如果需要）

一些 C 程序附带一个 Makefile，而另一些则附带一个名为 ./configure 的脚本。例如，如果你下载 sqlite 的源代码，它里面有一个 ./configure 脚本，而不是 Makefile。

我对这个 ./configure 脚本的理解是：

你运行它，它会输出大量难以理解的信息，然后它要么生成一个 Makefile，要么因为缺少某些依赖项而失败
./configure 脚本是 autotools 系统的一部分，我除了“运行它来生成 Makefile”之外，从未需要学习其他知识。

我认为可能有一些选项可以传递给 ./configure 脚本以生成不同的 Makefile，但我从未这样做过。

步骤 4：运行 `make`

下一步是运行 make 来尝试构建程序。关于 make 的一些说明：

有时你可以运行 make -j8 来并行化构建，使其更快
在编译程序时，它通常会输出大量编译器警告。我总是忽略它们。我没写这个软件！编译器警告不是我的问题。

编译器错误通常是依赖项问题

这是我在 Mac 上编译 paperjam 时遇到的一个错误：

/opt/homebrew/Cellar/qpdf/12.0.0/include/qpdf/InputSource.hh:85:19: error: function definition does not declare parameters
   85 |     qpdf_offset_t last_offset{0};
      |                   ^

多年来，我了解到最好不要太过度思考这类问题：如果它提到 qpdf，很可能只是意味着我在包含 qpdf 依赖项的方式上做错了什么。

现在，让我们谈谈一些正确包含 qpdf 依赖项的方法。

世界上最短的编译器和链接器介绍

在讨论如何修复依赖项问题之前：构建 C 程序分为两个步骤：

编译代码为目标文件（使用 gcc 或 clang）
将这些目标文件链接成最终的二进制文件（使用 ld）

构建 C 程序时知道这一点很重要，因为有时你需要向编译器和链接器传递正确的标志，以告诉它们在哪里找到你正在编译的程序的依赖项。

`make` 使用环境变量配置编译器和链接器

如果我在 Mac 上运行 make 来安装 paperjam，我会得到这个错误：

c++ -o paperjam paperjam.o pdf-tools.o parse.o cmds.o pdf.o -lqpdf -lpaper
ld: library 'qpdf' not found

这不是因为 qpdf 没有安装在我的系统上（实际上已经安装了！）。但是编译器和链接器不知道如何找到 qpdf 库。要修复这个问题，我们需要：

向编译器传递 "-I/opt/homebrew/include"（告诉它在哪里找到头文件）
向链接器传递 "-L/opt/homebrew/lib -liconv"（告诉它在哪里找到库文件，并链接 iconv）

我们可以让 make 通过环境变量向编译器和链接器传递这些额外参数！要了解这是如何工作的：在 paperjam 的 Makefile 中，你可以看到许多环境变量，比如这里的 LDLIBS：

paperjam: $(OBJS)
	$(LD) -o $@ $^ $(LDLIBS)

你放入 LDLIBS 环境变量的所有内容都会作为命令行参数传递给链接器（ld）。

秘密环境变量：`CPPFLAGS`

Makefiles 有时定义自己的环境变量并传递给编译器/链接器，但 make 还有许多“隐式”环境变量，它会自动传递给 C 编译器和链接器。这里有完整的隐式环境变量列表，但其中之一是 CPPFLAGS，它会自动传递给 C 编译器。

（严格来说，使用 CXXFLAGS 可能更正常，但这个特定的 Makefile 硬编码了 CXXFLAGS，所以设置 CPPFLAGS 是我找到的唯一方法，无需编辑 Makefile）

顺便说一句：我花了很长时间才意识到 `make` 与 C/C++ 的紧密关系——我曾认为 `make` 只是一个通用的构建系统（当然你可以用它来构建任何东西！），但它有许多针对构建 C/C++ 程序的便利功能，而这些功能在构建其他类型的程序时没有。

向 `make` 传递环境变量的两种方式

我通过 @zwol 了解到实际上有两种方式向 make 传递环境变量：

CXXFLAGS=xyz make（通常的方式）
make CXXFLAGS=xyz

它们之间的区别是 make CXXFLAGS=xyz 会覆盖 Makefile 中设置的 CXXFLAGS 的值，而 CXXFLAGS=xyz make 不会。

我不确定哪种方式是标准，但我将在本文中使用第一种。

如何使用 `CPPFLAGS` 和 `LDLIBS` 修复此编译器错误

现在我们已经讨论了 CPPFLAGS 和 LDLIBS 如何传递给编译器和链接器，以下是我最终成功构建程序的命令！

CPPFLAGS="-I/opt/homebrew/include" LDLIBS="-L/opt/homebrew/lib -liconv" make paperjam

这会将 -I/opt/homebrew/include 传递给编译器，将 -L/opt/homebrew/lib -liconv 传递给链接器。

另外，我不想假装我“神奇地”知道这些是正确的参数，找出它们涉及许多困惑的搜索，我在本文中跳过了。我会说：

-I 编译器标志告诉编译器在哪里找到头文件，如 /opt/homebrew/include/qpdf/QPDF.hh
-L 链接器标志告诉链接器在哪里找到库，如 /opt/homebrew/lib/libqpdf.a
-l 链接器标志告诉链接器链接哪些库，如 -liconv 表示“链接 iconv 库”，或 -lm 表示“链接数学库”

提示：如何只构建一个特定文件：`make $FILENAME`

昨天我发现了一个很酷的工具，叫做 qf，你可以用它从 ripgrep 的输出快速打开文件。

qf 位于一个包含各种工具的大目录中，但我只想编译 qf。所以我只编译了 qf，像这样：

make qf

基本上，如果你知道（或可以猜测）你正在构建的文件的输出文件名，你可以通过运行 make $FILENAME 来告诉 make 只构建那个文件。

提示：你不需要 Makefile

我有时编写没有依赖项的 5 行 C 程序，我刚学到如果我有一个名为 blah.c 的文件，我可以这样编译它，无需创建 Makefile：

make blah

它会被自动扩展为 cc -o blah blah.c，节省了一些打字。我不知道我是否会记住这个（我可能仍然会输入 gcc -o blah blah.c），但这似乎是一个有趣的技巧。

提示：查看其他打包系统如何构建相同的 C 程序

如果你在构建 C 程序时遇到困难，也许其他人也遇到过构建问题！每个 Linux 发行版都有每个构建包的构建文件，所以即使你不能直接从该发行版安装包，也许你可以从该 Linux 发行版获得如何构建包的提示。意识到这一点（感谢我的朋友 Dave）对我来说是一个巨大的顿悟时刻。

例如，nix 包中 paperjam 的这一行说：

  env.NIX_LDFLAGS = lib.optionalString stdenv.hostPlatform.isDarwin "-liconv";

这基本上是说“在 Mac 上构建时传递链接器标志 -liconv”，所以这是一个我们可以用来构建它的线索。

同一个文件还说 env.NIX_CFLAGS_COMPILE = "-DPOINTERHOLDER_TRANSITION=1";。我不确定这意味着什么，但当我尝试构建 paperjam 包时，我确实得到一个关于某个叫 PointerHolder 的错误，所以我猜这与“PointerHolder 过渡”有关。

步骤 5：安装二进制文件

一旦你成功编译了程序，你可能想要将其安装在某处！一些 Makefile 有一个 install 目标，允许你通过 make install 在系统上安装工具。我对此总是有点害怕（它会把文件放在哪里？如果我以后想卸载它们怎么办？），所以如果我编译的是一个相当简单的程序，我通常只是手动复制二进制文件来安装它，像这样：

cp qf ~/bin

步骤 6：也许制作你自己的包！

一旦我搞清楚了如何做所有这些事情，我意识到我可以利用我新的 make 知识为 Homebrew 贡献一个 paperjam 包！然后我就可以在未来的系统上直接 brew install paperjam。

好处是即使不同打包系统的细节不同，它们从根本上都使用 C 编译器和链接器。

即使你不是 C 程序员，了解一点 C 也很有用

我认为所有这些都是一个有趣的例子，说明了解 C 程序如何工作的基础知识（比如“它们有头文件”）即使你从未计划在你的生活中编写非平凡的 C 程序，也可能是有用的。

自己能够编译 C/C++ 程序感觉很好，尽管我仍然对所有的编译器和链接器标志不完全自信，并且我仍然计划除了“你运行 ./configure 来生成 Makefile”之外，不学习任何关于 autotools 如何工作的知识。

我在这篇文章中省略了两件事：

LD_LIBRARY_PATH / DYLD_LIBRARY_PATH（你使用它来告诉动态链接器在运行时在哪里找到动态链接的文件），因为我不记得最后一次遇到 LD_LIBRARY_PATH 问题是什么时候，而且找不到例子。
pkg-config，我认为这很重要，但我还不理解。

由 mimo-v2.5 模型翻译，花费 9379 tokens

ANSI 转义码的标准

Fri, 7 Mar 2025 00:00:00 +0000

[AI 摘要] 本文探讨了 ANSI 转义码的相关标准（如 ECMA-48、xterm 序列、terminfo）及其尚未完全统一的现状，展望了终端体验未来改善的可能性。

大家好！今天我想聊聊 ANSI 转义码。

长期以来，我对 ANSI 转义码只有一个模糊的概念（“就是在终端里把文字变红之类的东西”），但完全不清楚它们应该在哪里定义，是否存在相关标准。我对它们总有一种“神龙见首不见尾”的模糊感觉。今年在学习终端相关知识时，我了解到：

ANSI 转义码对终端的可用性改进功不可没（你知道在 SSH 连接到远程机器时，有办法复制到系统剪贴板吗？？这涉及到一个名为 OSC 52 的转义码！）
它们并未完全标准化，因此并不总是能可靠地工作。而且由于它们是不可见的，排查转义码相关问题会令人极其沮丧。

所以我想为自己整理一份关于现有转义码标准的清单，因为我想知道它们是否注定要显得不可靠且令人头疼，或者未来我们是否可以更放心地依赖它们。

什么是转义码？
ECMA-48
xterm 控制序列
terminfo
程序应该使用 terminfo 吗？
是否存在“单一通用集”的转义码？
使用 terminfo 的一些理由
更多文档/标准
为什么我觉得这很有趣

什么是转义码？

你是否曾在终端中按下左箭头键，然后看到 ^[[D？

那就是一个转义码！它被称为“转义码”，是因为第一个字符是“转义”字符，通常写作 ESC、\x1b、\E、\033 或 ^[。

转义码是你的终端模拟器与其中运行的程序进行各种信息（颜色、鼠标移动等）通信的方式。转义码有两种：

输入码：当按键或鼠标移动无法用 Unicode 表示时，你的终端模拟器会发送输入码。例如，“左箭头键”是 ESC[D，“Ctrl+左箭头”可能是 ESC[1;5D，而鼠标点击可能是类似 ESC[M :3 的东西。
输出码：程序可以打印输出码来着色文本、移动光标、清屏、隐藏光标、复制文本到剪贴板、启用鼠标报告、设置窗口标题等。

现在让我们来谈谈标准！

ECMA-48

我找到的第一个与转义码相关的标准是 ECMA-48，它最初发布于 1976 年。

ECMA-48 做了两件事：

定义了一些转义码的通用格式（比如“CSI”码，即 ESC[ 加上某些内容，以及“OSC”码，即 ESC] 加上某些内容）。
定义了一些具体的转义码，比如“将光标向左移动”是 ESC[D，或者“将文本变为红色”是 ESC[31m。在规范中，“光标左移”被称为 CURSOR LEFT，而用于改变颜色的则被称为 SELECT GRAPHIC RENDITION。

这些格式是可扩展的，因此为他人在未来定义更多转义码留出了空间。如今流行的许多转义码并未在 ECMA-48 中定义：例如，终端应用程序（如 vim、htop 或 tmux）通常支持使用鼠标，但 ECMA-48 并未定义鼠标的转义码。

xterm 控制序列

有许多转义码未在 ECMA-48 中定义，例如：

启用鼠标报告（你点击了终端的哪个位置？）
带括号粘贴（你是粘贴了那段文本还是手动输入的？）
OSC 52（终端应用程序可以使用它将文本复制到系统剪贴板）

我相信（如果我错了请纠正我！）这些以及一些其他的转义码源自 xterm，记录在 XTerm 控制序列中，并且已被其他终端模拟器广泛实现。

这份“xterm 支持什么”的清单严格来说并非一个标准，但 xterm 的影响力极大，因此它似乎是一份重要的文档。

terminfo

在 80 年代（某种程度上今天也如此，但据我理解在 80 年代要严重得多），终端实际支持的转义码存在巨大的差异。

为了应对这种情况，出现了一个名为“terminfo”的数据库，其中包含了各种终端的转义码信息。

terminfo 的标准似乎是 X/Open Curses，不过需要创建账户才能查看该标准（不知为何）。它定义了数据库格式以及用于访问数据库的 C 库接口（“curses”）。

例如，你可以运行这段 bash 代码片段来查看你的系统所知所有不同终端的“清屏”可能对应的所有转义码：

for term in $(toe -a | awk '{print $1}')
do
  echo $term
  infocmp -1 -T "$term" 2>/dev/null | grep 'clear=' | sed 's/clear=//g;s/,//g'
done

在我的系统上（以及可能我使用过的每一个系统？），terminfo 数据库由 ncurses 管理。

程序应该使用 terminfo 吗？

我认为有趣的是，应用程序处理 ANSI 转义码主要有两种方法：

使用 terminfo 数据库来确定使用哪些转义码，这取决于 TERM 环境变量的值。例如，Fish 就是这样做的。
识别一组在“足够多”终端模拟器中都能工作的“单一通用集”转义码，并直接硬编码它们。

一些采用方法 #2（“不使用 terminfo”）的程序/库的例子包括：

我好奇为什么人们可能正在远离 terminfo，然后发现了这篇非常有趣且极其详细的 Fish 维护者对 terminfo 的吐槽，其中认为：

（terminfo 作者们）做了大量当时极其重要且有益的工作。我的观点是，它现在已经不再那么重要了。

我无法充分概括它，所以我不打算总结它，但我认为它值得一读。

是否存在“单一通用集”的转义码？

我刚才谈到了使用一组适用于大多数人的“通用集”转义码的想法。但这个集合是什么？有任何共识吗？

我完全不知道这个问题的答案，但通过一些阅读，它似乎是一些组合：

VT100 支持的代码（尽管有些在现代终端上已不相关）
ECMA-48 中的内容（我认为其中也有一些不再相关的东西）
xterm 支持的内容（不过我猜其中并非所有内容都得到了足够广泛的实现）

最终可能还是“识别你认为用户最常使用的终端模拟器并在其中测试”，就像网页开发人员在决定可以使用哪些 CSS 功能时所做的那样。

不过我认为终端领域没有类似 Can I use…? 或 Baseline 的资源。（理论上 terminfo 应该是终端的“caniuse”，但当人们发明新终端功能时，它似乎通常需要 10 年以上才能添加，这使其非常局限。）

使用 terminfo 的一些理由

我也在 Mastodon 上问了为什么人们在 2025 年仍然认为 terminfo 有价值，得到了几个我认为合理的理由：

有些人期望能够使用 TERM 环境变量来控制程序的行为（例如使用 TERM=dumb），而在后 terminfo 时代，没有关于这应如何工作的标准。
尽管终端模拟器之间的差异比 80 年代少了，但远非零：有图形终端、Linux 帧缓冲控制台、通过串行控制台连接服务器的情况、Emacs shell 模式，以及可能我遗漏的其他情况。
不存在一个关于什么是“单一通用集”转义码的统一标准，而且有时程序使用的转义码实际上并未得到足够广泛的实现。

terminfo 和用户代理检测

ncurses 使用 TERM 环境变量来决定使用哪些转义码的方式，让我想起了过去网络服务器有时如何使用浏览器用户代理来决定提供哪个版本的网站。

它似乎也产生了一些相似的结果——iTerm2 将自己报告为“xterm-256color”的方式，类似于 Safari 的用户代理是“Mozilla/5.0 (Macintosh; Intel Mac OS X 14_7_4) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.3 Safari/605.1.15”。在这两种情况下，终端模拟器/浏览器最终都改变了它的用户代理，以绕过效果不佳的用户代理检测。

在 Web 上，我们最终决定用户代理检测不是一个好做法，转而专注于标准化，以便向所有浏览器提供相同的 HTML/CSS。但我不知道这种方法是否是终端的未来——我认为今天的终端格局比曾经的 Web 更加碎片化，而且资金也少得多。

为什么我觉得这很有趣

我有时会听到有人说 unix 终端是“过时的”，由于我非常喜爱终端，我总是好奇哪些增量变化可能会让它感觉不那么“过时”。

也许如果我们有一个更清晰的标准格局（就像在 Web 上那样！），终端模拟器开发者就能更容易地构建新功能，终端应用程序的作者也能更自信地采用这些功能，从而让我们所有人都能从中受益，并在终端中获得更丰富的体验。

显然，标准化 ANSI 转义码并不容易（ECMA-48 首次发布已近 50 年，而我们仍未做到！）。我甚至不知道所有的挑战是什么。但 HTML/CSS/JS 的情况曾经也极其糟糕，而现在好多了，所以也许还有希望。

由 mimo-v2.5 模型翻译，花费 7741 tokens

如何将目录添加到你的PATH

Thu, 13 Feb 2025 12:27:56 +0000

[AI 摘要] 本文提供了在bash、zsh和fish中添加目录到PATH环境变量的详细步骤、配置文件查找和常见问题解决方案。

今天我和一个朋友聊到如何将目录添加到PATH。对我来说，这似乎“显而易见”，因为我长期使用终端，但当我搜索操作说明时，实际上找不到一个解释所有步骤的——很多只是说“将此添加到~/.bashrc”，但如果你不用bash呢？如果你的bash配置文件在另一个文件里呢？而且，你该如何确定要添加哪个目录？

因此，我想尝试写下更完整的指导，并提及我多年来遇到的一些陷阱。

以下是目录：

步骤1：你使用的是哪个shell？
步骤2：找到你的shell配置文件
- 关于bash配置文件的说明
步骤3：确定要添加的目录
- 步骤3.1：确认是正确的目录
步骤4：编辑你的shell配置
步骤5：重启你的shell
问题：
备注：
- 关于source的说明
- 关于fish_add_path的说明

步骤1：你使用的是哪个shell？

如果你不确定自己使用哪个shell，这里有一个方法来找出。运行以下命令：

ps -p $$ -o pid,comm=

如果你使用bash，它会输出97295 bash
如果你使用zsh，它会输出97295 zsh
如果你使用fish，它会输出类似“In fish, please use $fish_pid”的错误（$$在fish中语法无效，但错误信息会告诉你使用的是fish，你可能已经知道）

此外，Linux上默认使用bash，Mac OS上默认使用zsh（截至2024年）。我只会在指导中涵盖bash、zsh和fish。

步骤2：找到你的shell配置文件

在zsh中，可能是~/.zshrc
在bash中，可能是~/.bashrc，但情况复杂，见下一节的说明
在fish中，可能是~/.config/fish/config.fish（如果你想要100%确定，可以运行echo $__fish_config_dir）

关于bash配置文件的说明

Bash有三个可能的配置文件：~/.bashrc、~/.bash_profile和~/.profile。

如果你不确定你的系统使用哪个，我建议这样测试：

将echo hi there添加到~/.bashrc
重启你的终端
如果看到“hi there”，表示~/.bashrc正在被使用！太好了！
否则，移除它并尝试同样的方法用~/.bash_profile
如果前两个选项都不起作用，也可以尝试~/.profile

（网上有很多详细的流程图解释bash如何决定使用哪个配置文件，但在我看来，内化它们不值得，直接测试是最快的方法）

步骤3：确定要添加的目录

假设你正在尝试安装并运行一个名为http-server的程序，但它不起作用，像这样：

$ npm install -g http-server
$ http-server
bash: http-server: command not found

你如何找到http-server所在的目录？老实说，这通常不容易——答案往往是“取决于npm如何配置”。几个想法：

通常当设置新的安装程序（如cargo、npm、homebrew等）时，首次设置时它会打印一些关于如何更新PATH的说明。所以如果你注意的话，可以那时获取说明。
有时安装程序会自动更新你的shell配置文件来更新PATH
有时直接谷歌“npm安装东西在哪里？”会找到答案
有些工具有子命令告诉你它们配置安装在哪里，例如：
- Node/npm：npm config get prefix（然后附加/bin/）
- Go：go env GOPATH（然后附加/bin/）
- asdf：asdf info | grep ASDF_DIR（然后附加/bin/和/shims/）

步骤3.1：确认是正确的目录

一旦你找到一个可能正确的目录，确保它确实是正确的！例如，我发现我的机器上http-server在~/.npm-global/bin中。我可以尝试在该目录运行程序http-server来确认是否正确：

$ ~/.npm-global/bin/http-server
Starting up http-server, serving ./public

它工作了！现在你知道需要添加到PATH的目录，让我们进入下一步！

步骤4：编辑你的shell配置

现在我们有了需要的两个关键信息：

要添加到PATH的目录（例如~/.npm-global/bin/）
你的shell配置文件的位置（例如~/.bashrc、~/.zshrc或~/.config/fish/config.fish）

现在需要添加的内容取决于你的shell：

bash指导：

打开你的shell配置文件，添加一行如下：

export PATH=$PATH:~/.npm-global/bin/

（显然将~/.npm-global/bin替换为你要添加的实际目录）

zsh指导：

你可以做与bash相同的事情，但zsh也有一些稍微花哨的语法，如果你喜欢的话可以使用：

path=(
  $path
  ~/.npm-global/bin
)

fish指导：

在fish中，语法不同：

set PATH $PATH ~/.npm-global/bin

（在fish中你也可以使用fish_add_path，下面有一些说明）

步骤5：重启你的shell

现在，一个极其重要的步骤：如果你不重启shell，更新你的shell配置不会生效！

两种方法：

打开一个新的终端（或终端标签页），也许关闭旧的以免混淆
运行bash启动新的shell（如果你使用zsh则运行zsh，使用fish则运行fish）

我发现这两种方法通常都工作得很好。

你应该完成了！尝试运行你试图运行的程序，希望它现在能工作。

如果没有，这里有一些你可能遇到的问题：

问题1：运行了错误的程序

如果运行的是程序的错误版本，你可能需要将目录添加到PATH的开头而不是末尾。

例如，在我的系统上，我安装了两个版本的python3，我可以通过运行which -a看到：

$ which -a python3
/usr/bin/python3
/opt/homebrew/bin/python3

你的shell将使用的第一个列出的版本。

如果你想使用Homebrew版本，你需要将该目录（/opt/homebrew/bin）添加到PATH的开头，在你的shell配置文件中这样写（是/opt/homebrew/bin/:$PATH而不是通常的$PATH:/opt/homebrew/bin/）

export PATH=/opt/homebrew/bin/:$PATH

或者在fish中：

set PATH ~/.cargo/bin $PATH

问题2：程序未从你的shell运行

所有这些指导仅当你在从你的shell运行程序时有效。如果你从IDE、GUI、cron作业或其他方式运行程序，你需要以不同的方式添加目录到PATH，具体情况可能取决于场景。

在cron作业中

一些选项：

使用程序的完整路径，例如/home/bork/bin/my-program
将完整的PATH作为crontab的第一行（类似PATH=/bin:/usr/bin:/usr/local/bin:...）。你可以通过运行echo "PATH=$PATH"获取你在shell中使用的完整PATH。

老实说，我不确定在IDE/GUI中如何处理，因为我很久没遇到过，如果有人指出正确方向，我会在这里添加指导。

问题3：重复的PATH条目使调试更难

如果你编辑PATH并运行bash（或zsh，或fish）启动新shell，通常会导致重复的PATH条目，因为每次启动shell时shell都会向PATH添加新内容。

我个人认为我没有遇到过这种重复导致任何问题的情况，但如果你试图理解PATH的内容，重复会使调试更难。

你可以处理的一些方法：

如果你正在调试PATH，打开一个新终端来做，这样你得到“新鲜”状态。这应该避免重复。
在shell配置文件末尾去重PATH（例如在zsh中，显然你可以用typeset -U path做到）
添加时检查目录是否已在PATH中（例如在fish中，我认为你可以用fish_add_path --path /some/directory做到）

如何在shell中去重PATH取决于shell，并不总是有内置方法，所以你需要查找如何在你的shell中完成。

问题4：更新PATH后丢失历史记录

这里是bash或zsh中容易遇到的情况：

运行一个命令（它失败）
更新PATH
运行bash重新加载配置
按上箭头几次重新运行失败的命令（或打开新终端）
失败的命令不在历史记录中！为什么？

这发生是因为在bash中，默认情况下，历史记录在退出shell之前不会保存。

修复的一些选项：

代替运行bash重新加载配置，运行source ~/.bashrc（或在zsh中source ~/.zshrc）。这将在当前会话内重新加载配置。
配置你的shell持续保存历史记录，而不是仅在shell退出时保存。（如何做到取决于你使用bash还是zsh，zsh中的历史选项有点复杂，我不太确定最佳方法）

关于`source`的说明

当你首次安装cargo（Rust的安装程序）时，它会给你这些设置PATH的说明，根本没有提到具体目录。

This is usually done by running one of the following (note the leading DOT):

. "$HOME/.cargo/env"        	# For sh/bash/zsh/ash/dash/pdksh
source "$HOME/.cargo/env.fish"  # For fish

这个想法是你将那行添加到你的shell配置，他们的脚本会自动设置你的PATH（以及其他可能的东西）。

这很常见（例如Homebrew建议你eval brew shellenv），有两种方法：

直接按工具的建议做（例如添加. "$HOME/.cargo/env"到你的shell配置）
弄清楚他们建议运行的脚本会添加哪些目录到PATH，然后手动添加。以下是我会做的方法：
- 在shell中运行. "$HOME/.cargo/env"（如果使用fish则用fish版本）
- 运行echo "$PATH" | tr ':' '\n' | grep cargo来弄清楚它添加了哪些目录
- 看到它说/Users/bork/.cargo/bin，缩短为~/.cargo/bin
- 将目录~/.cargo/bin添加到PATH（用本文中的指导）

我不认为按工具的建议做有什么问题（它可能是“最佳方式”！），但个人我通常使用第二种方法，因为我更喜欢确切知道我正在更改什么配置。

关于`fish_add_path`的说明

fish有一个方便的函数fish_add_path，你可以运行它来添加目录到PATH，像这样：

fish_add_path /some/directory

这很酷（它是一个简单的命令！），但我已经停止使用它，原因有几个：

有时fish_add_path会更新每个未来会话的PATH（用“通用变量”），有时它只更新当前会话的PATH，我很难判断它会做哪个。理论上文档解释了这一点，但我无法理解。
如果你需要在几周或几个月后从PATH中移除该目录（可能因为你犯了个错误），这有点难做到（不过这个github issue的评论中有说明）。

就这样了

希望这能帮助一些人。如果你有其他在添加目录到PATH时遇到的主要陷阱，或者对这篇文章有疑问，请告诉我（在Mastodon或Bluesky上）！

由 mimo-v2.5 模型翻译，花费 10235 tokens

一些终端使用中的挫败感

Wed, 5 Feb 2025 16:57:00 +0000

[AI 摘要] 该文分类总结了一项针对1600名资深终端用户的调查结果，列举了他们在使用终端时遇到的主要挫败点。

几周前，我进行了一次终端使用调查（你可以在此查看结果），在调查的最后我问了这样一个问题：

对你来说，使用终端最令人感到挫败的是什么？

有1600人回答了这个问题，我决定花几天时间将所有回复分类。在这个过程中，我了解到对定性数据进行分类并不容易，但我尽力了。为了加快分类速度，我专门构建了一个工具。

与我的所有调查一样，这个方法论并不是特别科学。我只是在Mastodon和Twitter上发布了调查，运行了几天，收集了那些恰好看到并愿意回答的人的意见。

以下是主要的挫败感类别！

我认为在阅读这些评论时，有必要记住以下几点：

参与此调查的人中，有40%使用终端已超过21年。
参与调查的人中，有95%使用终端至少有4年。

这些评论并非来自完全的初学者。

以下是各类挫败感！括号中的数字是持有该种挫败感的人数。我主要将这些记录下来是因为我自己正在尝试编写一本关于终端的小册子，我想了解人们遇到了哪些困难。

记忆语法（115）

人们提到了记忆以下内容的困难：

awk、jq、sed等命令行工具的语法
重定向的语法
tmux、文本编辑器等的快捷键

一个示例评论：

要掌握全部功能，有太多细小的“琐碎”细节需要记忆。即使过了这么多年，我有时还是会忘记标准错误输出是2还是1，或者忘记>和>>哪个是哪个。

切换终端环境很难（91）

人们提到了在切换系统（例如家庭/工作电脑或使用SSH时）时遇到的困难，包括：

不同操作系统键盘快捷键的差异（如Linux与Mac）
系统没有他们喜欢的文本编辑器（“没有vim”或“只有vim”）
同一命令的不同版本（如Mac OS的grep与GNU grep）
没有标签页补全
不熟悉的shell（“zsh和bash之间的细微差别”）

以及同一系统内部的差异，例如分页器彼此不一致（git diff的分页器、其他分页器）。

一个示例评论：

我习惯了fish和vi模式，但当我通过SSH连接到服务器或容器时，这些都不可用。

颜色（85）

颜色方面有很多问题，例如：

程序设置的颜色在浅色背景上难以阅读
找到一个喜欢的颜色方案（并使其在不同应用中保持一致）
颜色在多层SSH/tmux等中不起作用
不喜欢默认颜色
完全不想要颜色，却难以将其关闭

这条评论让我感同身受：

在终端模拟器和fish之间合理配置我的终端主题（我几年前做过这件事，记得当时非常繁琐和棘手，现在感觉被当前的主题“锁定”了，因为它能工作，我非常害怕再次触碰任何相关配置）。

键盘快捷键（84）

关于键盘快捷键的评论中，有一半是关于在Linux/Windows上，终端的复制/粘贴快捷键与操作系统其他部分不同。

除了复制/粘贴，还有一些其他快捷键问题：

在基于浏览器的终端中使用Ctrl-W却关闭了窗口
终端只支持有限的键盘快捷键（不支持Ctrl-Shift-、Super、Hyper，很多ctrl-快捷键不可能实现，比如Ctrl-,）
操作系统阻止你使用终端快捷键（例如，Mac OS默认使用Ctrl+左箭头做其他事情）
在终端中使用emacs遇到的问题
退格键不起作用（2人提到）

其他复制粘贴问题（75）

除了“复制粘贴的键盘快捷键不同”之外，还有很多其他复制粘贴问题，例如：

通过SSH复制
tmux和终端模拟器以不同方式处理复制粘贴
处理多个不同的剪贴板（系统剪贴板、vim剪贴板、Linux上的“中键点击”剪贴板、tmux的剪贴板等）并可能需要同步它们
从终端复制时随机添加空格
粘贴多行命令时会自动以令人恐惧的方式执行
希望有一种不使用鼠标就能复制文本的方法

可发现性（55）

有很多关于这方面的评论，都归结为同一个基本抱怨——很难发现有用的工具或功能！这条评论很好地总结了这一点：

自主学习有多难。我知道的大部分东西都是多年来随机的人们告诉我的零碎知识的集合。

陡峭的学习曲线（44）

很多评论提到它通常具有陡峭的学习曲线。举几个例子：

用了15年之后，我现在的速度并不比5年甚至10年前快多少。

以及

我知道通过学习更多关于快捷键和命令的知识以及配置终端，可以让我的生活更轻松，但我没有花时间去做，因为这感觉让人不堪重负。

历史记录（42）

一些shell历史记录的问题：

历史记录不在终端标签页之间共享（16人提到）
历史记录长度限制太短（4人提到）
恢复终端标签页时历史记录未被恢复
因终端崩溃而丢失历史记录
不知道如何搜索历史记录

一个示例评论：

在我弄明白之前，这浪费了很多时间，而且仍然让我烦恼的是，zsh上的“历史记录”缓冲区太小；我必须输入“history 0”才能获得任何有用长度的历史记录。

糟糕的文档（37）

人们提到了：

文档通常晦涩难懂
手册页缺乏示例
程序没有手册页

这是一条有代表性的评论：

找到好的示例和文档。手册页往往不够用，不得不在Stack Overflow中摸索。

回滚（36）

回滚方面的一些问题：

程序输出数据过多，导致丢失回滚历史
调整终端大小会搞乱回滚内容
缺少时间戳
在后台启动的GUI程序输出内容，干扰了其他程序的输出

一个示例评论：

调整终端大小（特别是：使其变窄）会导致回滚内容的重新换行出错，因为命令的输出格式是基于终端窗口宽度设置的。

“感觉过时”（33）

很多评论提到终端感觉受制于遗留决策，用户常常需要学习感觉非常深奥的实现细节。一个示例评论：

大多数遗留包袱，如果能有一个全新的命令行接口实现就好了。

Shell脚本（32）

很多关于POSIX shell脚本的抱怨。普遍感觉shell脚本很难，但转向其他不那么标准的脚本语言（如fish、nushell等）也会带来自己的问题。

Shell脚本。我放弃shell脚本而转向其他脚本语言的容忍度很低。它太混乱也太强大了。搞砸的代价可能很高，所以我甚至懒得去做。

无（122）

还有122个回答类似于“没什么”或“唯一的挫败是我无法在终端里做所有事情”。

一个示例评论：

我想我已经找到了解决大部分/所有挫败感的方法。

以上就是全部了！

我不打算对这些结果做过多评论，但以下是一些我认为相关的类别：

记忆语法和历史记录（通常需要记住的东西是你之前运行过的！）
可发现性和学习曲线（可发现性差绝对是学习困难的一个主要原因）
“切换系统很难”和“感觉过时”（那些30年或40年来几乎没有变化的工具有很多问题，但它们确实倾向于在任何系统上都存在，这非常有用，也使得它们很难被停用）

尝试以合理的方式对所有这些结果进行分类，真的让我对社会科学研究员的技能感到钦佩。

由 mimo-v2.5 模型翻译，花费 6257 tokens

什么是配置"现代"终端环境所涉及的？

Sat, 11 Jan 2025 09:46:01 +0000

[AI 摘要] 本文探讨了配置一个功能齐全的现代终端环境所涉及的复杂性和诸多挑战。

你好！最近我进行了一次终端使用调查，并询问了用户们对哪些方面感到困扰。其中一人评论道：

要获得现代终端体验，涉及太多组件了。真希望它们能开箱即用。

我最初的反应是“哦，配置现代终端体验并不难，你只需要……”，但想得越多，“你只需要……”的清单就越长，而且我不断想到越来越多的注意事项。

因此，我决定写些笔记，谈谈我个人对“现代”终端体验的理解，以及我认为什么因素让人们难以实现它。

什么是“现代终端体验”？

以下是我个人认为重要的几点，并注明了系统中由哪部分负责实现：

多行复制粘贴支持：如果你在shell中粘贴3条命令，它不应该立即全部执行！那太吓人了！（shell，终端模拟器）
无限的shell历史记录：如果我在shell中运行了一个命令，它应该被永久保存，而不是在500条历史记录后就被删除。另外，我希望命令在运行时立即保存到历史记录，而不是在退出shell会话时才保存（shell）
有用的提示符：没有在提示符中显示当前目录和当前git分支，我简直无法工作（shell）
24位色：这对我很重要，因为发现在支持24位色的终端中配置neovim的主题比在仅支持256色的终端中容易得多（终端模拟器）
剪贴板集成：让vim和我的操作系统实现剪贴板集成，这样当我在Firefox中复制内容后，只需在vim中按p键就能粘贴（文本编辑器，可能还需要操作系统/终端模拟器的支持）
良好的自动补全：例如，git这类命令应该有针对其特定命令的补全（shell）
ls命令带颜色（shell配置）
我喜欢的终端主题：我花很多时间在终端里，我希望它看起来美观，并且其主题能与我的终端编辑器主题匹配。（终端模拟器，文本编辑器）
自动修复终端：如果某个程序输出了一些奇怪的转义代码弄乱了终端，我希望能够自动重置，这样终端就不会一团糟（shell）
快捷键绑定：我希望Ctrl+左箭头能正常工作（shell或应用程序）
在less等程序中能够使用滚轮：（终端模拟器和应用程序）

终端便利性功能有无数种，不同的人看重不同的方面，但这些是我无法缺少的功能。

我如何实现“现代体验”

我的基本方法是：

使用fish shell。基本不做配置，除了：
- 将EDITOR环境变量设置为我最喜欢的终端编辑器
- 将ls别名设置为ls --color=auto
使用任何支持24位色的终端模拟器。过去我用过GNOME Terminal、Terminator和iTerm，但我对此并不挑剔。除了选择字体外，我基本不配置它。
使用neovim，配合我过去大约9年来非常缓慢构建的配置（我上次删除vim配置并从头开始是9年前的事了）
使用base16框架为所有内容设置主题

影响我方法的一些因素：

我不常SSH到其他机器上工作
与其想出基于键盘的方式来完成所有事情，我宁愿稍微使用鼠标
我处理很多小项目，而不是一个大项目

一些“开箱即用”的“现代”体验选项

如果你想要一个良好的体验，但又不想花大量时间在配置上呢？搞清楚如何配置vim让我满意确实花了我大概十年，那可是很长的时间！

关于如何以最小配置获得合理终端体验，我的最佳建议是：

shell：要么使用fish，要么使用zsh配合oh-my-zsh
终端模拟器：几乎所有支持24位色的都可以，例如以下这些都很流行：
- Linux：GNOME Terminal、Konsole、Terminator、xfce4-terminal
- Mac：iTerm（Terminal.app不支持256色）
- 跨平台：kitty、alacritty、wezterm或ghostty
shell配置：
- 将EDITOR环境变量设置为你最喜欢的终端文本编辑器
- 也许可以将ls别名设置为ls --color=auto
文本编辑器：这是个难题，也许micro或helix？我都没有认真使用过它们，但它们看起来都是非常酷的项目，而且我认为你能直接在micro中使用所有常见的GUI编辑器命令（Ctrl-C复制、Ctrl-V粘贴、Ctrl-A全选）并且它们能按预期工作，这太棒了。我可能会尝试切换到helix，但重新训练我的vim肌肉记忆似乎太难了。而且helix目前还没有GUI或插件系统。

就个人而言，我不会使用xterm、rxvt或Terminal.app作为终端模拟器，因为我过去发现它们缺少核心功能（比如Terminal.app的24位色支持），这会让我的终端使用起来更困难。

我并不想假装获得“现代”终端体验比实际更容易——我认为有两个问题让它变得困难。我们来谈谈吧！

获得“现代”体验的问题一：shell

bash和zsh是目前最流行的两个shell，它们都没有提供我愿意开箱即用的默认体验，例如：

你需要自定义提示符
它们默认不带git补全功能，你需要自己设置
默认情况下，bash只存储500（！）条历史记录，而（至少在Mac OS上）zsh默认只配置存储2000条，这仍然不算多
我发现bash的标签页补全非常令人沮丧，如果存在多个匹配项，你无法通过标签页切换

尽管我喜欢fish，但它不符合POSIX标准的事实确实让很多人难以转换。

当然，学习如何在bash中自定义提示符是完全可能的，而且甚至不需要太复杂（在bash中我可能会从类似export PS1='[\u@\h \W$(__git_ps1 " (%s)")]\$ '的配置开始，或者使用starship）。但每一个这些“不复杂”的事情确实会累积起来，特别是当你需要在多个系统上同步配置时，情况就更糟了。

获得“现代”shell体验的一个极其流行的解决方案是oh-my-zsh。它看起来是个很棒的项目，我知道很多人用得非常开心，但我过去在使用类似配置系统时遇到了困难——看起来目前基础的oh-my-zsh添加了大约3000行配置，而且我常常发现，额外的配置系统会让事情出错时的调试变得更困难。我个人倾向于使用这个系统添加很多额外插件，导致系统变慢，然后对速度感到沮丧，最后完全删除它并从头开始写新配置。

获得“现代”体验的问题二：文本编辑器

在我最近进行的终端调查中，最受欢迎的终端文本编辑器无疑是vim、emacs和nano。

我认为终端文本编辑器的主要选择有：

使用vim或emacs并根据你的喜好进行配置，如果你投入时间，你可能可以获得任何想要的功能
使用nano并接受你将获得相当有限的体验（例如，我认为你不能在nano中用鼠标选择文本然后“剪切”）
使用micro或helix，它们似乎提供了相当好的开箱即用体验，但可能会偶尔遇到使用非主流文本编辑器的问题
尽量避免使用终端文本编辑器，也许使用VSCode，使用VSCode的终端满足所有终端需求，并且几乎从不在终端中编辑文件。或者我知道很多人在终端中使用code作为他们的EDITOR。

问题三：单个应用程序

最后一个问题是，有时我使用的单个程序会有点烦人。例如，在我的Mac OS机器上，/usr/bin/sqlite3不支持Ctrl+左箭头快捷键。修复这个问题以在SQLite中获得合理的终端体验有点复杂，我不得不：

意识到问题发生的原因（Mac OS不提供GNU工具，而“Ctrl-左箭头”支持来自GNU readline）
找到解决方法（从homebrew安装sqlite，它确实有readline支持）
调整我的环境（将Homebrew的sqlite3放入我的PATH）

我发现调试这类应用程序特定的问题真的不容易，而且常常觉得不“值得”——我通常会处理各种小不便，因为不想花几个小时去研究它们。我能够弄清楚这个问题的唯一原因是我最近花了大量时间思考终端问题。

使用终端程序获得“现代”体验的一个重要部分是使用更新的终端程序，例如，我不愿费心学习在top中排序列的快捷键，但在htop中，我只需用鼠标点击列标题就能排序。所以我改用htop！但发现新的更“现代”的命令行工具并不容易（不过我在此列出了一个清单），找到实际喜欢使用的工具需要时间，而且如果你SSH到另一台机器，它们可能并不总是可用。

一切都会影响其他一切

配置终端让一切变得“好用”的一个棘手之处在于，改变工作流中一个看似微小的方面可能会真正影响其他一切。例如，我现在不使用tmux。但如果我需要再次使用tmux（例如，因为我需要SSH到另一台机器上做大量工作），我就需要考虑几件事，比如：

如果我想让tmux的复制与我的系统剪贴板在SSH上同步，我需要确保我的终端模拟器支持OSC 52
如果我想使用iTerm的tmux集成（它将tmux标签页变成iTerm标签页），我就需要改变我设置颜色的方式——目前我在shell启动时运行一个shell脚本来设置颜色，但这意味着恢复tmux会话时颜色会丢失。

可能还有更多我没考虑到的事情。“使用tmux意味着我必须改变管理颜色的方式”听起来不太可能，但这确实发生在我身上，我决定“好吧，我现在不想改变管理颜色的方式，所以我想我不会使用那个功能了！”

也很难记住我依赖哪些功能——例如，也许我当前的终端确实支持OSC 52，并且因为通过SSH从tmux复制一直都能正常工作，我甚至没意识到那是我需要的东西，然后当我切换终端时它神秘地停止工作。

缓慢地改变

就个人而言，即使我认为我的设置并不那么复杂，我也花了20年才达到这个水平！因为终端配置更改很可能产生意想不到且难以理解的结果，我发现如果我一次性更改大量终端配置，一旦出现问题，就很难理解哪里出错了，这会让人非常困惑。

所以我通常倾向于做出非常小的改变，并接受改变可能需要我花非常长的时间来适应。例如，我一两年前从使用ls切换到了eza，虽然我喜欢它（因为eza -l默认打印人类可读的文件大小），但我仍然不太确定。但有时进行大的改变是值得的，比如我10年前从bash切换到fish，我非常高兴我这样做了。

获得“现代”终端并不那么容易

试图解释配置终端有多“容易”实际上只是让我想到它有点难，而且我有时仍然会感到困惑。

我发现终端中从来没有一种完美的配置方式能与每一件其他事情兼容。我只需要尝试，找到某种对我来说局部稳定的状态，并接受如果我开始使用一个新工具，它可能会打乱系统，我可能需要重新思考。

由 mimo-v2.5 模型翻译，花费 7997 tokens

终端程序所遵循的“规则”

Thu, 12 Dec 2024 09:28:22 +0000

[AI 摘要] 这篇文章描述了终端程序遵循的一些常见但非官方的、观察到的行为“规则”。

最近我一直在思考，终端中发生的一切都是以下部分的某种组合：

你的操作系统的任务
你的shell的任务
你的终端模拟器的任务
你恰好正在运行的程序（比如 top 或 vim 或 cat）的任务

前三个（你的操作系统、shell和终端模拟器）都算是已知量——如果你在Linux上的GNOME终端中使用bash，你大概可以推断出所有这些组件如何互动，它们的一些行为也被POSIX标准化。

但第四个（“你恰好正在运行的程序”）感觉可能做任何事情。你怎么知道一个程序会如何表现？

这篇文章有点长，所以这里有一个快速的目录：

程序表现得出奇地一致
这些是描述性的，而非规定性的
并非总是显而易见哪些“规则”是程序应实现的责任
规则1：非交互式程序应在你按 Ctrl-C 时退出
规则2：TUI应在你按 q 时退出
规则3：REPL应在你按 Ctrl-D 时退出
规则4：不要使用超过16种颜色
规则5：大致支持readline键绑定
规则5.1：Ctrl-W 应删除最后一个单词
规则6：写入管道时禁用颜色
规则7：- 表示标准输入/标准输出
这些“规则”需要很长时间才能学会

程序表现得出奇地一致

据我所知，关于终端中的程序应如何行为，并没有真正的标准——我所知道的最接近的是：

POSIX，它主要规定了你的终端模拟器/OS/shell应如何协同工作。我认为它确实指定了cp等核心工具的一些行为，但据我所知，它没有对例如htop应如何表现发表任何意见。
这些命令行界面指南。

但尽管没有标准，根据我的经验，终端中的程序行为相当一致。所以我想写下一份程序大多遵循的“规则”清单。

这些是描述性的，而非规定性的

我这里的目标不是说服终端程序作者他们应该遵循任何这些规则。这些规则有很多例外，而且这些例外通常有很好的理由。

但对我来说，知道一个随机的新终端程序会有什么行为非常有用。与其说“呃，程序可能做任何事”，不如说“好的，这里有我期望的基本规则，然后我可以保留一份简短的例外清单”。

所以我只是写下我对我使用终端20年来所观察到的程序行为方式的总结，我认为它们这样行为的原因，以及一些“打破”该规则的例子。

并非总是显而易见哪些“规则”是程序应实现的责任

有一些常见的约定，我认为显然是程序应实现的责任，比如：

配置文件应放在 ~/.BLAHrc 或 ~/.config/BLAH/FILE 或 /etc/BLAH/ 之类的地方
--help 应打印帮助文本
程序应将“常规”输出打印到标准输出，错误打印到标准错误

但在这篇文章中，我将专注于那些不100%明显是程序责任的事情。例如，对我来说，按 Ctrl-D 应该退出REPL感觉像一条“自然法则”，但程序通常需要明确实现支持——即使 cat 不需要实现 Ctrl-D 支持，ipython 需要。（更多关于此的内容见下文“规则3”）

理解哪些事情是程序的责任，可以使不同程序的实现略有不同时，减少意外感。

规则1：非交互式程序应在你按 `Ctrl-C` 时退出

这条规则的主要原因是，非交互式程序如果在没有设置 SIGINT 信号处理程序的情况下，按 Ctrl-C 时默认会退出，所以这有点像“你应该表现得像默认行为”的规则。

让很多人困惑的是，这不适用于交互式程序，如 python3 或 bc 或 less。这是因为在交互式程序中，Ctrl-C 有另一个作用——如果程序正在运行一个操作（例如 less 中的搜索或 python3 中的一些Python代码），那么 Ctrl-C 会中断该操作，但不会停止程序。

作为交互式程序中如何工作的一个例子：这是prompt-toolkit（iPython用于处理输入的库）中的代码，当你按 Ctrl-C 时会中止搜索。

规则2：TUI应在你按 `q` 时退出

TUI程序（如 less 或 htop）通常在你按 q 时退出。

这条规则不适用于任何按 q 退出没有意义的程序，比如 tmux 或文本编辑器。

规则3：REPL应在你按 `Ctrl-D` 时退出

REPL（如 python3 或 ed）通常在你按 Ctrl-D 时退出。这条规则类似于 Ctrl-C 规则——原因是默认情况下，如果你在一个以“烹饪模式”运行的程序（如 cat）中，操作系统会在你按 Ctrl-D 时返回一个 EOF。

我使用的大多数REPL（sqlite3、python3、fish、bash等）实际上并不使用烹饪模式，但它们都实现了这个键盘快捷键来模仿默认行为。

例如，这是prompt-toolkit中当你按Ctrl-D时退出的代码，而这是readline中相同的代码。

我实际上在很久以前认为这是一个“终端物理定律”，因为我基本上从未见过它被打破，但你可以从上面的链接看到，这只是每个单独的输入库必须实现的东西。

有人指出Erlang REPL在按 Ctrl-D 时不会退出，所以我想并非每个REPL都遵循这个“规则”。

规则4：不要使用超过16种颜色

终端程序很少使用基本16种ANSI颜色之外的颜色。这是因为如果你用十六进制代码指定颜色，很可能会与某些用户的背景颜色冲突。例如，如果我打印一些颜色为 #EEEEEE 的文本，在白色背景上它几乎是看不见的，但在深色背景上看起来还不错。

但如果你坚持使用默认的16种基本颜色，你就有更大的机会让用户在终端模拟器中配置这些颜色，使它们与背景颜色配合得相当好。坚持使用默认16种基本颜色的另一个原因是，它对终端模拟器支持什么颜色的假设较少。

我通常看到打破这条“规则”的唯一程序是文本编辑器，例如Helix默认使用紫色背景，这不是默认的ANSI颜色。Helix打破这条规则似乎没问题，因为Helix不是一个“核心”程序，我假设任何不喜欢该配色方案的Helix用户会直接更改主题。

规则5：大致支持readline键绑定

我使用的几乎每个程序，如果这样做有意义，都支持 readline 键绑定。例如，以下是许多不同的程序和链接到它们定义 Ctrl-E 到行尾的位置：

ipython（Ctrl-E定义在这里）
atuin（Ctrl-E定义在这里）
fzf（Ctrl-E定义在这里）
zsh（Ctrl-E定义在这里）
fish（Ctrl-E定义在这里）
tmux的命令提示符（Ctrl-E定义在这里）

这些程序都不直接使用 readline，它们只是模仿emacs/readline键绑定。它们并不总是完全模仿它们：例如atuin似乎使用 Ctrl-A 作为前缀，所以 Ctrl-A 不会到行首。

另外所有这些程序似乎都实现了自己的内部剪切和粘贴缓冲区，所以你可以用 Ctrl-U 删除一行，然后用 Ctrl-Y 粘贴它。

例外是：

一些程序（如 git、cat 和 nc）没有任何行编辑支持（除了退格键、Ctrl-W 和 Ctrl-U）
一如既往，文本编辑器是个例外，每个文本编辑器都有自己的文本编辑方法

我在在终端中输入文本很复杂中写了更多关于这个“程序支持哪些键绑定？”问题的内容。

规则5.1：`Ctrl-W` 应删除最后一个单词

我从未见过一个程序（除了文本编辑器）Ctrl-W不删除最后一个单词。这类似于 Ctrl-C 规则——默认情况下，如果一个程序在“烹饪模式”下，操作系统会在你按 Ctrl-W 时删除最后一个单词，按 Ctrl-U 时删除整行。所以程序通常会模仿这种行为。

除了文本编辑器，我想不出任何其他例外，但如果有的话我很想听听！

规则6：写入管道时禁用颜色

大多数程序在写入管道时会禁用颜色。例如：

rg blah 会在输出中高亮显示所有 blah 的出现，但如果输出到管道或文件，它会关闭高亮。
ls --color=auto 在写入终端时会使用颜色，但在写入管道时不会

这两个程序在写入终端时也会格式化输出：ls会将文件组织成列，ripgrep会用标题分组匹配项。

如果你想强制程序使用颜色（例如因为你想要查看颜色），你可以使用 unbuffer 强制程序的输出像这样成为tty：

unbuffer rg blah |  less -R

我确信有一些程序“打破”了这条规则，但我现在想不出任何例子。一些程序有一个 --color 标志，你可以用来强制颜色开启，在上面的例子中，你也可以这样做 rg --color=always | less -R。

规则7：`-` 表示标准输入/标准输出

通常，如果你向程序传递 - 而不是文件名，它会从标准输入读取或写入标准输出（以适当的方式）。例如，如果你想用 black 格式化你剪贴板上的Python代码然后复制它，你可以运行：

pbpaste | black - | pbcopy

（pbpaste 是Mac程序，你可以在Linux上用 xclip 做类似的事情）

我的印象是，大多数程序如果这样做有意义都会实现这一点，我现在想不出任何例外，但我确信有很多例外。

这些“规则”需要很长时间才能学会

这些规则花了我很长时间才学会，因为我必须：

学习该规则是否适用（“Ctrl-C 将退出程序”）
注意到一些例外（“好的，Ctrl-C 将退出 find 但不退出 less”）
下意识地弄清楚模式是什么（“Ctrl-C 通常会退出非交互式程序，但在交互式程序中它可能会中断当前操作而不是退出程序”）
最终也许将其制定成我所知道的明确规则

老实说，我对终端的很多理解仍然处于“潜意识模式识别”阶段。我之所以花时间使事情明确化的唯一原因是因为我一直在试图向其他人解释它如何工作。希望将这些“规则”明确地写下来能让其他人学习这些内容快一点。

由 mimo-v2.5 模型翻译，花费 9608 tokens

管道为何有时会“卡住”：缓冲机制

Fri, 29 Nov 2024 08:23:31 +0000

[AI 摘要] 本文解释了Unix管道有时输出延迟的原因是程序缓冲机制，并提供了多种解决方案来禁用缓冲。

这是一个困扰我多年的终端小众问题，但直到几周前我才真正理解。假设你运行以下命令来监视日志文件中的特定输出：

tail -f /some/log/file | grep thing1 | grep thing2

如果日志行添加到文件的速度相对较慢，我看到的结果就是……什么都没有！无论日志文件中是否有匹配项，都不会有任何输出。

我默认接受了这个现象：“呃，我猜管道有时候就是会卡住，不显示输出，真奇怪”，然后我会改用 grep thing1 /some/log/file | grep thing2 来处理，这样就能工作。

所以在过去几个月深入研究终端时，我非常兴奋地终于明白了这到底是为什么。

原因：缓冲

“管道卡住”的原因在于，程序在将输出写入管道或文件之前进行缓冲是非常常见的做法。所以管道本身工作正常，问题在于程序根本没有将数据写入管道！

这是出于性能考虑：立即将所有输出写入会使用更多系统调用，因此更高效的做法是积累数据直到有大约 8KB 的数据要写入（或直到程序退出），然后再将其写入管道。

在这个例子中：

tail -f /some/log/file | grep thing1 | grep thing2

问题在于 grep thing1 会保存所有匹配项，直到积累大约 8KB 的数据才写入，而这可能永远不会发生。

程序写入终端时不进行缓冲

我觉得这很令人困惑的部分原因是，tail -f file | grep thing 完全可以正常工作，但当你添加第二个 grep 时，它就停止工作了！原因是 grep 处理缓冲的方式取决于它是否写入终端。

以下是 grep（以及许多其他程序）决定如何缓冲输出的方式：

使用 isatty 函数检查标准输出是否为终端
- 如果是终端，则使用行缓冲（立即打印每一行）
- 否则使用“块缓冲”——只有在有大约 8KB 或更多数据时才打印

因此，如果 grep 直接写入你的终端，你会立即看到输出；但如果写入管道，你就看不到了。

当然，每个程序的缓冲大小不总是 8KB，这取决于实现。对于 grep，缓冲由 libc 处理，而 libc 的缓冲区大小定义在 BUFSIZ 变量中。这是 glibc 中的定义位置。

（顺便说一句：“程序写入终端时不使用 8KB 输出缓冲区”并非终端物理定律，程序完全可以使用 8KB 缓冲区写入终端，但这会非常奇怪，我想不出任何程序会这样行为）

缓冲命令与不缓冲命令

这种缓冲行为的一个烦人之处在于，你需要记住哪些命令在写入管道时会缓冲输出。

一些不缓冲输出的命令：

tail
cat
tee

我认为几乎所有其他命令都会缓冲输出，特别是那些你可能用于批量处理的命令。以下是一些常见命令的列表，它们在写入管道时会缓冲输出，以及禁用块缓冲的标志。

grep (--line-buffered)
sed (-u)
awk（有 fflush() 函数）
tcpdump (-l)
jq (-u)
tr (-u)
cut（无法禁用缓冲）

这些就是我能想到的所有命令，许多其他 Unix 命令（如 sort）可能会缓冲输出也可能不会，但这无关紧要，因为 sort 在完成接收输入之前无法做任何事。

另外，我尽力测试了 Mac OS 和 GNU 版本的这些命令，但存在很多差异，我可能犯了一些错误。

默认“print”语句会缓冲的编程语言

此外，以下是一些编程语言，其默认 print 语句在写入管道时会缓冲输出，以及一些禁用缓冲的方法（如果你需要）：

C（使用 setvbuf 禁用）
Python（使用 python -u，或 PYTHONUNBUFFERED=1，或 sys.stdout.reconfigure(line_buffering=False)，或 print(x, flush=True) 禁用）
Ruby（使用 STDOUT.sync = true 禁用）
Perl（使用 $| = 1 禁用）

我假设这些语言这样设计是为了让默认的 print 函数在批量处理时速度更快。

另外，输出是否缓冲可能取决于你的打印方式，例如在 C++ 中，cout << "hello\n" 在写入管道时会缓冲，但 cout << "hello" << endl 会刷新输出。

在管道上按 `Ctrl-C` 时，缓冲区内容会丢失

假设你运行这个命令作为一种 hacky 方式来监视到 example.com 的 DNS 请求，而你忘了给 tcpdump 传递 -l：

sudo tcpdump -ni any port 53 | grep example.com

当你按 Ctrl-C 时，会发生什么？在一个理想的完美世界中，我希望发生的是 tcpdump 刷新其缓冲区，grep 搜索 example.com，然后我就能看到所有错过的输出。

但在现实中，所有程序都被终止，tcpdump 缓冲区中的输出丢失了。

我想这个问题可能无法避免——我花了一点时间用 strace 查看这是如何工作的，grep 在 tcpdump 之前接收到 SIGINT，所以即使 tcpdump 尝试刷新缓冲区，grep 也已经死了。

经过进一步调查，有一个解决方法：如果你找到 tcpdump 的 PID 并执行 kill -TERM $PID，那么 tcpdump 会刷新缓冲区，你就可以看到输出了。这有点麻烦，但我测试过，似乎有效。

重定向到文件也会缓冲

不仅仅是管道，这个也会缓冲：

sudo tcpdump -ni any port 53 > output.txt

重定向到文件没有相同的“Ctrl-C 会完全销毁缓冲区内容”的问题——根据我的经验，它通常表现得更符合预期，缓冲区的内容会在程序退出前写入文件。我不完全确定这是否总是可以依赖的。

一系列避免缓冲的潜在方法

好的，让我们来讨论解决方案。假设你运行了这个命令：

tail -f /some/log/file | grep thing1 | grep thing2

我在 Mastodon 上询问人们如何在实践中解决这个问题，有 5 种基本方法。如下：

解决方案1：运行一个快速完成的程序

历史上，我的解决方案是完全避免“命令缓慢写入管道”的情况，而是运行一个能快速完成的程序，像这样：

cat /some/log/file | grep thing1 | grep thing2 | tail

这与原始命令的作用不同，但它确实意味着你可以避免思考这些奇怪的缓冲问题。

（你也可以使用 grep thing1 /some/log/file，但我经常更喜欢使用一个“不必要”的 cat）

解决方案2：记住 grep 的行缓冲标志

你可以记住 grep 有一个避免缓冲的标志，并像这样传递它：

tail -f /some/log/file | grep --line-buffered thing1 | grep thing2

解决方案3：使用 awk

有些人说，如果他们特别处理多个 grep 的情况，他们会重写为使用单个 awk，像这样：

tail -f /some/log/file |  awk '/thing1/ && /thing2/'

或者你会编写更复杂的 grep，像这样：

tail -f /some/log/file |  grep -E 'thing1.*thing2'

（awk 也会缓冲，所以为了让它工作，你希望 awk 是管道中的最后一个命令）

解决方案4：使用 `stdbuf`

stdbuf 使用 LD_PRELOAD 来关闭 libc 的缓冲，你可以像这样用它来关闭输出缓冲：

tail -f /some/log/file | stdbuf -o0 grep thing1 | grep thing2

像任何 LD_PRELOAD 解决方案一样，它有点不可靠——它不适用于静态二进制文件，我认为如果程序不使用 libc 的缓冲就不工作，并且在 Mac OS 上并不总是有效。Harry Marr 有一篇很棒的 stdbuf 工作原理文章。

解决方案5：使用 `unbuffer`

unbuffer program 会强制程序的输出为 TTY，这意味着它的行为方式就像在 TTY 上一样（更少缓冲、彩色输出等）。你可以在本例中这样使用它：

tail -f /some/log/file | unbuffer grep thing1 | grep thing2

与 stdbuf 不同，它总是有效，尽管它可能有不想要的副作用，例如 grep thing1 也会为匹配项着色。

如果你想安装 unbuffer，它在 expect 包中。

这些就是我所知的所有解决方案！

对我来说，很难说哪个“最好”，我个人最可能使用 unbuffer，因为我知道它总是有效。

如果我了解到更多解决方案，我会尝试将它们添加到这篇文章中。

我不确定这经常发生

对我来说，程序缓慢地向管道流入数据的情况并不常见，通常如果我使用管道，大量数据会快速写入，由管道中的所有内容处理，然后所有程序退出。我目前能想到的例子有：

tcpdump
tail -f
以不同方式监视日志文件，如 kubectl logs
缓慢计算的输出

如果有环境变量来禁用缓冲会怎样？

我认为如果有一个标准的环境变量来关闭缓冲，就像 Python 中的 PYTHONUNBUFFERED，会很酷。我从 Mark Dominus 在 2018 年的几篇博客文章中得到了这个想法。也许可以像 NO_COLOR 那样使用 NO_BUFFER？

设计似乎很难正确；Mark 指出 NETBSD 有名为 STDBUF、STDBUF1 等的环境变量，可以让你对缓冲有很多控制，但我想大多数开发者不想实现许多不同的环境变量来处理一个相对较小的边缘情况。

我也好奇是否有任何程序只是在一段时间后（比如 1 秒）自动刷新其输出缓冲区。理论上感觉会很好，但我想不出任何程序这样做，所以我想象有一些缺点。

我遗漏的内容

这篇文章没有讨论的一些事情，因为最近这些文章已经变得相当长，说真的，真的有人想读 3000 字关于缓冲的文章吗？

行缓冲与完全无缓冲输出的区别
向 stderr 缓冲与向 stdout 缓冲的不同
本文只讨论程序内部发生的缓冲，你的操作系统的 TTY 驱动程序有时也会进行一点缓冲
除了“你正在写入管道”之外，你可能需要刷新输出的其他原因

由 mimo-v2.5 模型翻译，花费 7797 tokens

如何在无构建系统的情况下导入前端 JavaScript 库

Mon, 18 Nov 2024 09:35:42 +0000

[AI 摘要] 本文介绍了在没有构建系统的情况下导入前端JavaScript库的方法，包括不同文件类型的识别和使用工具如import maps、esm.sh等。

我喜欢在没有构建系统的情况下编写 JavaScript（without a build system），昨天我又一次遇到了需要在不使用构建系统的情况下导入 JavaScript 库的问题，花了很长时间才弄清楚如何导入，因为库的设置说明假定你正在使用构建系统。

幸运的是，到现在我基本上已经学会了如何处理这种情况，要么成功使用该库，要么决定它太难而切换到另一个库，所以这是我希望多年前就有的关于导入 JavaScript 库的指南。

我将只讨论在前端使用 JavaScript 库，并且只关于如何在无构建系统的设置中使用它们。

在这篇文章中，我将讨论：

库可能提供的三种主要 JavaScript 文件类型（ES 模块、"经典"全局变量类型和 CommonJS）
如何确定 JavaScript 库在其构建中包含了哪些类型的文件
在代码中导入每种类型文件的方法

三种 JavaScript 文件类型

库可以提供 3 种基本类型的 JavaScript 文件：

定义全局变量的"经典"类型文件。这种文件你可以直接使用
然后我就可以使用全局 Chart 环境变量来使用该库。不能更简单了。我只是将 chart.umd.js 复制到我的 Git 仓库中，这样我就不用担心使用 NPM 或 CDN 挂掉之类的问题。

构建文件并不总是在 dist 目录中

许多库会将其构建放在 dist 目录中，但并非总是如此！构建文件的位置在库的 package.json 中指定。

例如，这里是 Chart.js 的 package.json 的一个摘录。
```
  "jsdelivr": "./dist/chart.umd.js",
  "unpkg": "./dist/chart.umd.js",
  "main": "./dist/chart.cjs",
  "module": "./dist/chart.js",
```
我认为这是说如果你想使用 ES 模块（module），你应该使用 dist/chart.js，但 jsDelivr 和 unpkg CDN 应该使用 ./dist/chart.umd.js。我猜 main 是用于 Node 的。

chart.js 的 package.json 还说 "type": "module"，根据这个文档，这告诉 Node 默认将文件视为 ES 模块。我认为它并没有具体告诉我们哪些文件是 ES 模块，哪些不是，但它确实告诉我们其中一些是 ES 模块。

示例库 2：@atcute/oauth-browser-client

@atcute/oauth-browser-client 是一个用于在浏览器中使用 OAuth 登录 Bluesky 的库。

让我们看看它在其构建中提供了哪些类型的 JavaScript 文件！
```
$ npm install @atcute/oauth-browser-client
$ cd node_modules/@atcute/oauth-browser-client/dist
$ ls *js
constants.js  dpop.js  environment.js  errors.js  index.js  resolvers.js
```
这里似乎唯一合理的根文件是 index.js，它看起来像这样：
```
export { configureOAuth } from './environment.js';
export * from './errors.js';
export * from './resolvers.js';
```
这种 export 语法意味着它是一个 ES 模块。这意味着我们可以在没有构建步骤的情况下在浏览器中使用它！让我们看看如何做到这一点。

如何使用带有 importmaps 的 ES 模块

使用 ES 模块并不像只添加一个

我们需要 import map 而不是像 import { BrowserOAuthClient } from "./oauth-client-browser.js" 这样做的原因是，该模块内部有更多的导入语句，比如 import {something} from @atcute/client，我们需要告诉浏览器从哪里获取 @atcute/client 及其所有其他依赖项的代码。

这是我为 @atcute/oauth-browser-client 使用的 importmap 的样子：

让这些 import maps 工作相当棘手，我觉得一定有一个工具可以自动生成它们，但我还没找到。肯定可以写一个脚本使用 esbuild 的 metafile 自动生成 importmaps，但我还没这么做，也许有更好的方法。

我昨天决定设置 importmaps 来让 github.com/jvns/bsky-oauth-example 运行，所以那个仓库里有一些示例代码。

另外，有人向我指出了 Simon Willison 的 download-esm，它将下载一个 ES 模块并重写导入以直接指向 JS 文件，这样你就不需要 importmaps。我还没试过，但看起来是个好主意。

importmaps 的问题：文件太多

但我确实在浏览器中使用 importmaps 时遇到了一些问题——它需要下载几十个 JavaScript 文件来加载我的网站，而我的开发环境中的 Web 服务器不知为何跟不上。我不断看到文件随机加载失败，然后不得不重新加载页面，希望这次能成功。

当我将网站部署到生产环境时，这个问题就不再存在了，所以我想这是我的本地开发环境的问题。

另外，关于 ES 模块的普遍一个稍微烦人的事情是你需要运行一个 Web 服务器来使用它们，我确信这是有充分理由的，但当你只需打开你的 index.html 文件而无需启动 Web 服务器时，这更容易。

由于"文件太多"的问题，我认为实际上以这种方式使用带有 importmaps 的 ES 模块对我来说并不那么有吸引力，但知道它是可能的很好。

如何在不使用 importmaps 的情况下使用 ES 模块

如果 ES 模块没有依赖项，那就更容易了——你不需要 importmaps！你可以直接：

在你的 HTML 中放。type="module" 很重要。
在 YOURCODE.js 中放 import {whatever} from "https://example.com/whatever.js"。

替代方案：使用 esbuild

如果你不想使用 importmaps，你也可以使用像 esbuild 这样的构建系统。我在 Some notes on using esbuild 中谈到了如何做，但这篇博文是关于完全避免构建系统的方法，所以我不会在这里讨论那个选项。我仍然喜欢 esbuild，我认为在这种情况下它是一个好选择。

importmaps 的浏览器支持如何？

CanIUse 说 importmaps 处于"Baseline 2023：主要浏览器新近可用"，所以我的感觉是在 2024 年这仍然可能有点太新了？我想我会对一些有趣的实验性代码使用 importmaps，这些代码只供像我这样的人和 12 个人使用，但如果我想让我的代码更广泛可用，我会使用 esbuild。

示例库 3：`@atproto/oauth-client-browser`

让我们看看最后一个示例库！这是一个与 @atcute/oauth-browser-client 不同的 Bluesky 认证库。

$ npm install @atproto/oauth-client-browser
$ cd node_modules/@atproto/oauth-client-browser/dist
$ ls *js
browser-oauth-client.js  browser-oauth-database.js  browser-runtime-implementation.js  errors.js  index.js  indexed-db-store.js  util.js

同样，这里似乎唯一真正的候选文件是 index.js。但这是一个与之前示例库不同的情况！让我们看看 index.js：

在 index.js 中有一堆像这样的东西：

__exportStar(require("@atproto/oauth-client"), exports);
__exportStar(require("./browser-oauth-client.js"), exports);
__exportStar(require("./errors.js"), exports);
var util_js_1 = require("./util.js");

这种 require() 语法是 CommonJS 语法，这意味着我们根本不能在浏览器中使用这个文件，我们需要某种构建步骤，而且 ESBuild 也不行。

另外，在这个库的 package.json 中，它说 "type": "commonjs"，这是另一种表明它是 CommonJS 的方式。

如何使用 esm.sh 来使用 CommonJS 模块

最初我以为在不学习构建系统的情况下使用 CommonJS 模块是不可能的，但后来有人在 Bluesky 上告诉了我 esm.sh！它是一个将任何东西转换成 ES 模块的 CDN。skypack.dev 做类似的事情，我不确定区别是什么，但有人提到如果一个不行，有时他们会尝试另一个。

对于 @atproto/oauth-client-browser，使用它似乎很简单，我只需要在 HTML 中放这个：

然后在 script.js 中放这个。

import { BrowserOAuthClient } from "https://esm.sh/@atproto/oauth-client-browser@0.3.0"

它似乎就能正常工作，这很酷！当然，这仍然是在某种程度上使用构建系统——只是 esm.sh 在运行构建而不是我。我对这种方法的主要担忧是：

我并不真正信任 CDN 会永远保持工作——通常我喜欢将依赖项复制到我的仓库中，这样它们就不会因为某些原因在未来消失。
我听说 CDN 有安全问题，这让我害怕。
我并不真正理解 esm.sh 在做什么。

esbuild 也可以将 CommonJS 模块转换为 ES 模块

我还了解到，你也可以使用 esbuild 将 CommonJS 模块转换为 ES 模块，尽管有一些限制——import { BrowserOAuthClient } from 语法不起作用。这是一个关于此的 GitHub 问题。

我认为 esbuild 方法可能比 esm.sh 方法更吸引我，因为它是我电脑上已有的工具，所以我更信任它。不过，我还没怎么实验过这个。

三种文件类型总结

以下是三种 JS 文件类型的总结，如何使用它们，以及如何识别它们。

没有帮助的是，.js 或 .min.js 文件扩展名可能是这三种选项中的任何一种，所以如果文件是 something.js，你需要做更多的调查工作来弄清楚你在处理什么。

"经典" JS 文件
- 如何使用：
- 识别方式：
  - 该网站在其设置说明中有一个大的友好横幅，写着"使用此与 CDN！"或类似内容。
  - .umd.js 扩展名。
  - 尝试将其放入

julia-evans

远离 Tailwind，学习构建我的 CSS 结构

事实证明 Tailwind 教了我很多

我要谈论的系统

1. 重置

2. 组件

3. 颜色

4. 字体大小

5. 工具类

6. 基础样式

7. 间距

8. 响应式设计：使用更多网格！

9. 构建系统：esbuild

为什么迁离 Tailwind？

我好奇的 CSS 功能

我迁离 Tailwind 的最后一个原因

目前就这些！

CSS 色板资源链接

我最喜欢的

更多调色板

配色方案生成器

oklch

在浏览器中测试Vue组件

想法：直接在浏览器标签页中运行测试

测试框架：QUnit

第一步：为测试设置组件

第二步：添加一些测试夹具数据

第三步：一个基本测试

等待页面的某些部分渲染

弄清楚要等待的正确事情并不简单

添加一些CSS类来标识事物（但这样对吗？）

填写表格很棘手

测试覆盖率

这太有趣了！

tcpdump和dig手册页示例

目标：包含最基础的示例

为何要改进手册页？

关于避免编写手册页语言

手册页很复杂

关于改进手册页的笔记

选项摘要

按类别组织的选项部分

速查表

示例非常受欢迎

目录和部分之间的链接

每个选项的示例

在表格中格式化数据

GNU 的方法

一些与手册页相关的工具

思考受限格式很有趣

开始使用 Django 的一些笔记

比 Rails 魔法少

一个内置的管理后台

拥有一个 ORM 很有趣

自动迁移！

我喜欢文档

使用 sqlite

内置的电子邮件（以及更多）

设置文件仍然感觉很多

这就是目前的所有内容了！

Git 的数据模型（及其他文档更新）

Git 的一个数据模型

更新 git push、git pull 及更多内容

让测试读者识别问题

手册页的改动

关于为 Git 贡献代码的流程

从vim切换到Helix的笔记

为什么选择 Helix：语言服务器

搜索功能很棒

快速参考提示很好

一些 Vim 到 Helix 的键位映射

一些令我烦恼的 Helix 问题

切换比想象中容易

使用基于终端的文本编辑器

我的配置

我们拭目以待

新Zine：终端的神秘规则

目录

为什么是终端？

规则没有被写在任何地方

`oklch`

更新 `git push`、`git pull` 及更多内容

步骤 3：运行 `./configure`（如果需要）

步骤 4：运行 `make`

`make` 使用环境变量配置编译器和链接器

秘密环境变量：`CPPFLAGS`

向 `make` 传递环境变量的两种方式

如何使用 `CPPFLAGS` 和 `LDLIBS` 修复此编译器错误

提示：如何只构建一个特定文件：`make $FILENAME`

关于`source`的说明

关于`fish_add_path`的说明