4Ark

每周轮子之 server-only：一个空包背后的“毒药”

Wed, 24 Dec 2025 00:00:00 GMT

前言

三年前写过两篇《每周轮子》系列文章，讲如何从零实现一个日常都在用的 npm 包。其中的乐趣就是看看自己实现和别人有什么不一样，同时也能开阔视野。

现在迎来第三篇，这次我们将目光转向 React Server Components（说到转，旧手机可以找…

毕竟众所周知，这个月初 Next.js 圈子大型翻车现场，先后爆出几个 CVE，最出名的当属 CVE-2025-55182，据闻我们的大善人 Cloudflare 两周崩两次也是因为它，逼得我几次在群里嘴臭。

（PHP 有一个很经典的漏洞叫作 PHP Object Injection）

当我知道这个 CVE 时，上 fofa 随便挑选一位幸运倒霉蛋进行测试，很容易就利用上了：

结果没过几天，又来一个 CVE-2025-55183，这是一个会泄露 RSC 组件源码的漏洞，说到源码泄露，这就要引出本文的主角了：server-only。

几乎所有最佳实践都告诉我们：在服务端代码顶部加上 import 'server-only'，可以避免源码泄露。

今天突发奇想，想看看它是怎么实现的。

v1 Runtime Check

按照惯性思维，如果让我实现一个 server-only，我第一反应是写个运行时检查。既然代码不能在浏览器跑，那我就检测 window 对象嘛。

// 我脑补的 server-only
if (typeof window !== "undefined") {
  throw new Error("❌ 严重安全错误：服务端模块泄露到了客户端！");
}

这看起来很合理，对吧？

但这完全是错的。

Dan 在 How imports work in RSC 里讲得很清楚：哪怕你声明 'use server'，但只要构建工具（Webpack/Turbopack）看到你 import 了，它就会把代码打包进去。

也就是说，用上面这种方式，虽然页面报错了，但你的服务端代码依然存在于浏览器下载的 JS 文件里。只要别人右键查看源码，依然泄露。

典型“脱裤子放屁”——甚至更离谱，因为你觉得你安全了。

v2 Poison Pill

既然 Runtime 检查太晚了，我们必须在 Build Time（构建时）拦截它。

那 server-only 是怎么做的，如果你点开它的 npm 页面，你会发现它什么都没有，没有 README.md 甚至没有 git repo，你甚至都不知道它的作者是谁。

然后我打开 code 一看就这么简单：

server-only
├── index.js
├── empty.js
└── package.json

（这不比传说中的 is-odd 还简陋？）

里面的文件就是：

// index.js
throw new Error(
  "This module cannot be imported from a Client Component module. " +
    "It should only be used from a Server Component."
);

// empty.js
// 没错这个就是空的

细究之后才发现，这是一种毒药模式，简单说就是利用 Node.js 的条件导出实现一个精分 npm 包：

{
  "name": "server-only",
  "description": "This is a marker package to indicate that a module can only be used in Server Components.",
  "files": ["index.js", "empty.js"],
  "main": "index.js",
  "exports": {
    ".": {
      "react-server": "./empty.js",
      "default": "./index.js"
    }
  }
}

react-server 是什么？很明显它不是 Node.js 的规范，而是 React 团队定义的一种规范，代表了 RSC 的运行时环境。

这也是给所有第三方库用的一种标准，所以在 Next.js (或者其他 RSC 框架) 的构建时，它实现会跑两条 Pipelines：

Server Bundle：在这个流水线下，所有 import 都会优先寻找 package.json 里的 react-server 入口。
Client Bundle：正常跑

当 server-only 这个包被服务端引入，它就是一个空文件，被客户端引入它就报错，这就是毒药。

还有高手？

我在研究过程中，顺藤摸瓜看了下 Next.js 仓库里的 Issue #71071，发现事情还没这么简单。

1. 作者之谜

这个包最早的出处来自这个 PR，其实这个包只是 Next.js 内部使用，所以它什么都没有。

2. Tree-shaking 的漏网之鱼

你可能会问：如果我只引入了类型呢？

// ClientComponent.tsx
import type { UserType } from "./db-schema"; // 引用了 server-only 的文件

结论是：安全的。现代构建工具足够聪明，import type 会在编译阶段被移除，根本不会触发 server-only 的解析逻辑。

但是，如果你写成这样：

import { UserType, dbInstance } from "./db-schema";

即使你在代码里完全没用到 dbInstance，只是想用一下 UserType，构建工具依然会去解析这个文件，然后触发 server-only 的报错。

3. npm 包作者应有的觉悟

以前我们开发一个 npm 包，package.json 里写个 main 和 module 就完事了。但在 RSC 时代，如果你开发的库（比如一个数据库 ORM 客户端）不希望被误用到前端，你必须手动加上 react-server 的导出条件。

但如果你很不幸使用了一个没跟上节奏的 npm 包，那你得自觉地贴上 import 'server-only'。

一文讲透 Etherpad 插件开发

Thu, 18 Dec 2025 01:29:00 GMT

Etherpad 是什么

Etherpad 是一款基于 Node.js 的开源实时协作编辑器，能让很多人同时在线编辑，团队用它写文章、新闻稿、会议记录或者待办事项都很方便。跟 Google Docs 比，它最大的优点是数据可以自己管，扩展性也很强。

本文不重复官方文档里那些基础的东西，而是结合实际，好好讲讲怎么开发一个集成了“富文本、组件化内容、多渠道发布”的插件。

Etherpad 大概长这样：

技术架构

Etherpad 用的是全栈 JavaScript，靠 Socket.io 做实时通信，还用 OT 算法解决多人同时编辑的冲突。

前端 (jQuery + Ace2)：页面用 jQuery 搭，编辑器核心是用 iframe 装着的 Ace2（基于 contentEditable 做的），负责接收输入，生成 Changeset。

后端 (Node.js + UeberDB)：负责管 WebSocket 连接，合并 Changeset，然后广播出去。

插件系统 (Hook)：系统在关键的地方（比如 padInitToolbar, getLineHTMLForExport）留了 Hook 让你加东西。

插件怎么做？

官方建议一个功能搞一个 npm 包，但如果要深度定制，这样做太麻烦了。建议建一个插件合集（比如叫 ep_plugins）。

我做的这个插件集合主要有三件事：

增强编辑器 (Ace)：加了字体颜色、荧光笔、高亮字号、超链接、图片（包括删除）、图片脚注这些功能。
内容组件化：用“自定义标签（<ep-*>）”来放复杂的内容（题图卡片、主题卡片、往期阅读卡片、公众号关注卡片、腾讯视频、文章目录</ep-*>等等），在编辑器里看着就像可以编辑的文本，导出或者发布的时候再解析成 HTML。
发布和外部系统整合：把 Etherpad 的内容变成 Markdown，再变成不同渠道（微信公众号 / WordPress）的 HTML，通过后端接口发出去，还提供预览和一键复制功能。

设计思路：

编辑的时候：用 Etherpad 的 attribute（changeset attribution）存样式信息（比如：color=#f13b03、url=https://...），然后在 Ace 渲染的时候转成 CSS class 或者 DOM 结构，这样编辑起来更顺手。
导出/同步的时候：从 pad 的 AText（文本 + attribution）生成“增强版 Markdown”，把样式/组件用 <ep-*> 标签留着；然后用 marked 和自定义扩展把 <ep-*> 变成不同渠道的</ep-xx></ep-xx> HTML。

开发行内样式（拿“字体颜色”举例）

行内样式开发流程：UI 触发 → 写入属性 → 渲染样式。

注册 UI 和写入属性 (Client Side)

先在工具栏注册按钮，然后监听下拉框的变化，调用 documentAttributeManager 写入数据。

// static/js/index.js

// 1. 监听工具栏初始化 (Hook: postToolbarInit)
exports.postToolbarInit = (hook, context) => {
  const toolbar = context.toolbar;

  // 注册下拉框变化事件
  toolbar.registerCommand("fontColor", value => {
    const ace = context.ace;
    ace.callWithAce(
      ace => {
        // 给当前选区打上 color 属性
        ace.ace_setAttributeOnSelection("color", value);
      },
      "fontColor",
      true
    );
  });
};

将属性映射为 CSS Class (Client Side)

Etherpad 默认不认识 color 属性，需要我们告诉它如何渲染。

// static/js/index.js

// 2. 属性转 Class (Hook: aceAttribsToClasses)
exports.aceAttribsToClasses = (hook, context) => {
  // 如果属性名是 color，生成 .color__#xxxxxx 的 class
  if (context.key === "color") {
    return [`color__${context.value.replace("#", "")}`];
  }
};

// 3. 注入 CSS 样式 (Hook: aceInitInnerdocbodyHead)
// 注意：样式必须注入到 ace_inner iframe 中
exports.aceInitInnerdocbodyHead = (hook, context) => {
  return [
    `
    <style>
      /* 动态匹配所有颜色 class */
      [class*="color__"] { display: inline; }
      /* 这里通常需要动态生成 CSS，或者使用 CSS 变量方案 */
      .color__f13b03 { color: #f13b03; }
    </style>
  `,
  ];
};

内容组件化（自定义标签 DSL）

对于题图、目录、视频等复杂内容，我们使用 自定义标签（Custom Tags） 作为载体。

Marked 扩展构建器

为了让系统能识别 <ep-toc> 或 <ep-url>，我们需要扩展 marked 解析器。这是整个组件化系统的基石。

<summary><strong>build-marked-extension.js</strong></summary>

const cheerio = require("cheerio");

/**
 * 创建 marked 自定义扩展，实现自定义 block token
 * @param {string} name token 名字
 * @param {string} tagName 标签名字
 * @param {Function} renderer 渲染器
 * @returns
 */
function buildCustomBlockTokenExtension(name, tagName, { renderer }) {
  return {
    name,

    level: "block",

    tokenizer(src) {
      const rule = new RegExp(
        `^<ep-${tagName}\\b[^>]*>\\n([\\s\\S]*?)\\n<\\/ep-${tagName}>`
      );

      const match = rule.exec(src);

      if (match) {
        const $ = cheerio.load(`<body>${match[0]}</body>`);

        const attrs = getAllAttributes($(`body > ep-${tagName}`).get(0));

        const token = {
          type: name,
          raw: match[0],
          text: match[1].trim(),
          tokens: [],
          attrs,
        };

        this.lexer.blockTokens(token.text, token.tokens);

        return token;
      }

      return undefined;
    },

    renderer,
  };
}

/**
 * 创建 marked 自定义扩展，实现自定义 inline token
 * @param {string} name token 名字
 * @param {string} tagName 标签名字
 * @param {Function} renderer 渲染器
 * @returns
 */
function buildCustomInlineTokenExtension(name, tagName, { renderer }) {
  return {
    name,

    level: "inline",

    start(src) {
      return src.match(new RegExp(`<ep-${tagName}>`))?.index;
    },

    tokenizer(src) {
      const rule = new RegExp(
        `^<ep-${tagName}\\b[^>]*>((?:(?!<\\/ep-${tagName}>)[\\s\\S])*?)<\\/ep-${tagName}>`
      );

      const match = rule.exec(src);

      if (match) {
        const $ = cheerio.load(`<body>${match[0]}</body>`);

        const attrs = getAllAttributes($(`body > ep-${tagName}`).get(0));

        return {
          type: name,
          raw: match[0],
          text: match[1].trim(),
          tokens: this.lexer.inlineTokens(match[1].trim()),
          attrs,
        };
      }

      return undefined;
    },

    renderer,
  };
}

/**
 * 使用自定义标签包裹
 * @param {string} tagName
 * @param {string} content
 * @param {object} attrs
 * @returns
 */
function useCustomTag(tagName, content, attrs = {}) {
  const contentText = content ? `\n${content}\n` : "";

  if (Object.keys(attrs).length) {
    const attrsText = Object.entries(attrs)
      .map(([k, v]) => `${k}="${v}"`)
      .join(" ");

    return `<ep-${tagName} ${attrsText}>${contentText}</ep-${tagName}>`;
  }

  return `<ep-${tagName}>${contentText}</ep-${tagName}>`;
}

const getAllAttributes = function (node) {
  const attributes =
    node.attributes ||
    Object.keys(node.attribs).map(name => ({
      name,
      value: node.attribs[name],
    }));

  return attributes.reduce((acc, cur) => {
    return {
      [cur.name]: cur.value,
      ...acc,
    };
  }, {});
};

module.exports = {
  buildCustomBlockTokenExtension,
  buildCustomInlineTokenExtension,
  useCustomTag,
};

</details>

实现 TOC 目录组件

利用上面的构建器，我们可以快速定义一个目录组件的渲染逻辑。

// 注册 TOC 扩展
const { marked } = require("marked");
const { buildCustomBlockTokenExtension } = require("./build-marked-extension");

const tocExtension = buildCustomBlockTokenExtension("toc", "toc", {
  renderer(token) {
    // token.text 内容示例："🧩:: 第一节标题\n🔍:: 第二节标题"
    const items = token.text.split("\n").filter(Boolean);

    const html = items
      .map(line => {
        const [emoji, text] = line.split("::");
        return `<div class="toc-item"><span>${emoji}</span><a>${text}</a></div>`;
      })
      .join("");

    return `<section class="toc-container">${html}</section>`;
  },
});

// 加载扩展
marked.use({ extensions: [tocExtension] });

多渠道发布系统 (Send2CMS)

这是最复杂的模块：将 Pad 的 AText 数据转换为“增强版 Markdown”，再渲染为 HTML。

AText 转增强 Markdown

我们需要编写转换器，遍历 AText 的 attribs，将 color 属性还原为 <ep-color> 标签。

<summary><strong>get-pad-markdown-document.js (点击展开)</strong></summary>

const Changeset = require("ep_etherpad-lite/static/js/Changeset");
const padManager = require("ep_etherpad-lite/node/db/PadManager");

const { CUSTOM_TAGS } = require("../config");

const { correctLink } = require("./index");

const getCloseableTags = apool => {
  const normalTags = ["**", "*", ["<u>", "</u>"], "~~"];
  const normalProps = ["bold", "italic", "underline", "strikethrough"];

  const customAttrs = [
    CUSTOM_TAGS.COLOR,
    CUSTOM_TAGS.HIGHLIGHT,
    CUSTOM_TAGS.FONT_SIZE,
    CUSTOM_TAGS.URL,
    CUSTOM_TAGS.IMAGE_CAPTION,
  ];
  const customProps = [];

  apool.eachAttrib((k, v) => {
    if (customAttrs.includes(k)) {
      if (v !== "false") {
        customProps.push([k, v]);
      }
    }
  });

  const props = [...normalProps.map(p => [p, true]), ...customProps];
  const tags = [
    ...normalTags.map(tag => {
      const tags = Array.isArray(tag) ? tag : [tag, tag];

      const [open, close] = tags;

      return {
        open,
        close,
      };
    }),
    ...customProps.map(([k, v]) => ({
      open: `<ep-${k} ${k}="${v}">`,
      close: `</ep-${k}>`,
    })),
  ];
  const anumMap = {};

  props.forEach(([propName, propValue], i) => {
    const propTrueNum = apool.putAttrib([propName, propValue], true);

    if (propTrueNum >= 0) {
      anumMap[propTrueNum] = i;
    }
  });

  return { props, tags, anumMap };
};

const getMarkdownFromAtext = (pad, atext) => {
  const apool = pad.apool();
  const textLines = atext.text.slice(0, -1).split("\n");
  const attribLines = Changeset.splitAttributionLines(
    atext.attribs,
    atext.text
  );
  const { tags, props, anumMap } = getCloseableTags(apool);

  props.forEach((propName, i) => {
    const propTrueNum = apool.putAttrib([propName, true], true);

    if (propTrueNum >= 0) {
      anumMap[propTrueNum] = i;
    }
  });

  const headingtags = [
    "# ",
    "## ",
    "### ",
    "#### ",
    "##### ",
    "###### ",
    "    ",
  ];
  const headingprops = [
    ["heading", "h1"],
    ["heading", "h2"],
    ["heading", "h3"],
    ["heading", "h4"],
    ["heading", "h5"],
    ["heading", "h6"],
    ["heading", "code"],
  ];
  const headinganumMap = {};

  headingprops.forEach((prop, i) => {
    let name;
    let value;
    if (typeof prop === "object") {
      [name, value] = prop;
    } else {
      name = prop;
      value = true;
    }
    const propTrueNum = apool.putAttrib([name, value], true);
    if (propTrueNum >= 0) {
      headinganumMap[propTrueNum] = i;
    }
  });

  const getLineMarkdown = (text, attribs) => {
    const propVals = [false, false, false];
    const ENTER = 1;
    const STAY = 2;
    const LEAVE = 0;

    // Use order of tags (b/i/u) as order of nesting, for simplicity
    // and decent nesting.  For example,
    // <b>Just bold<b> <b><i>Bold and italics</i></b> <i>Just italics</i>
    // becomes
    // <b>Just bold <i>Bold and italics</i></b> <i>Just italics</i>
    const taker = Changeset.stringIterator(text);
    let assem = Changeset.stringAssembler();

    const openTags = [];
    const emitOpenTag = i => {
      openTags.unshift(i);
      assem.append(tags[i].open);
    };

    const emitCloseTag = i => {
      openTags.shift();
      assem.append(tags[i].close);
    };

    const orderdCloseTags = tags2close => {
      for (let i = 0; i < openTags.length; i++) {
        for (let j = 0; j < tags2close.length; j++) {
          if (tags2close[j] === openTags[i]) {
            emitCloseTag(tags2close[j]);
            i--;
            break;
          }
        }
      }
    };

    // start heading check
    let heading = false;
    let deletedAsterisk = false; // we need to delete * from the beginning of the heading line
    const iter2 = Changeset.opIterator(Changeset.subattribution(attribs, 0, 1));
    if (iter2.hasNext()) {
      const o2 = iter2.next();

      // iterate through attributes
      Changeset.eachAttribNumber(o2.attribs, a => {
        if (a in headinganumMap) {
          const i = headinganumMap[a]; // i = 0 => bold, etc.
          heading = headingtags[i];
        }
      });
    }

    if (heading) {
      assem.append(heading);
    }

    const urls = _findURLs(text);

    let idx = 0;

    const processNextChars = numChars => {
      if (numChars <= 0) {
        return;
      }

      const iter = Changeset.opIterator(
        Changeset.subattribution(attribs, idx, idx + numChars)
      );
      idx += numChars;

      while (iter.hasNext()) {
        const o = iter.next();
        let propChanged = false;
        Changeset.eachAttribNumber(o.attribs, a => {
          if (a in anumMap) {
            const i = anumMap[a]; // i = 0 => bold, etc.
            if (!propVals[i]) {
              propVals[i] = ENTER;
              propChanged = true;
            } else {
              propVals[i] = STAY;
            }
          }
        });
        for (let i = 0; i < propVals.length; i++) {
          if (propVals[i] === true) {
            propVals[i] = LEAVE;
            propChanged = true;
          } else if (propVals[i] === STAY) {
            propVals[i] = true; // set it back
          }
        }

        // now each member of propVal is in {false,LEAVE,ENTER,true}
        // according to what happens at start of span
        if (propChanged) {
          // leaving bold (e.g.) also leaves italics, etc.
          let left = false;
          for (let i = 0; i < propVals.length; i++) {
            const v = propVals[i];
            if (!left) {
              if (v === LEAVE) {
                left = true;
              }
            } else if (v === true) {
              propVals[i] = STAY; // tag will be closed and re-opened
            }
          }

          const tags2close = [];

          for (let i = propVals.length - 1; i >= 0; i--) {
            if (propVals[i] === LEAVE) {
              // emitCloseTag(i);
              tags2close.push(i);
              propVals[i] = false;
            } else if (propVals[i] === STAY) {
              // emitCloseTag(i);
              tags2close.push(i);
            }
          }

          orderdCloseTags(tags2close);

          for (let i = 0; i < propVals.length; i++) {
            if (propVals[i] === ENTER || propVals[i] === STAY) {
              emitOpenTag(i);
              propVals[i] = true;
            }
          }
          // propVals is now all {true,false} again
        } // end if (propChanged)
        let { chars } = o;
        if (o.lines) {
          chars--; // exclude newline at end of line, if present
        }

        let s = taker.take(chars);

        // removes the characters with the code 12. Don't know where they come
        // from but they break the abiword parser and are completly useless
        s = s.replace(String.fromCharCode(12), "");

        // delete * if this line is a heading
        if (heading && !deletedAsterisk) {
          s = s.substring(1);
          deletedAsterisk = true;
        }

        assem.append(s);
      } // end iteration over spans in line

      const tags2close = [];
      for (let i = propVals.length - 1; i >= 0; i--) {
        if (propVals[i]) {
          tags2close.push(i);
          propVals[i] = false;
        }
      }

      orderdCloseTags(tags2close);
    }; // end processNextChars

    if (urls) {
      urls.forEach(urlData => {
        const startIndex = urlData[0];
        const url = urlData[1];
        const urlLength = url.length;
        processNextChars(startIndex - idx);
        assem.append(`[${url}](`);
        processNextChars(urlLength);
        assem.append(")");
      });
    }

    processNextChars(text.length - idx);

    // replace &, _
    assem = assem.toString();
    assem = assem.replace(/&/g, "\\&");
    // this breaks Markdown math mode: $\sum_i^j$ becomes $\sum\_i^j$
    assem = assem.replace(/_/g, "\\_");

    return assem;
  };
  // end getLineMarkdown
  const pieces = [];

  // Need to deal with constraints imposed on HTML lists; can
  // only gain one level of nesting at once, can't change type
  // mid-list, etc.
  // People might use weird indenting, e.g. skip a level,
  // so we want to do something reasonable there.  We also
  // want to deal gracefully with blank lines.
  // => keeps track of the parents level of indentation
  const lists = []; // e.g. [[1,'bullet'], [3,'bullet'], ...]
  for (let i = 0; i < textLines.length; i++) {
    const line = _analyzeLine(textLines[i], attribLines[i], apool);
    let lineContent = getLineMarkdown(line.text, line.aline);

    // If we are inside a list
    if (line.listLevel) {
      // do list stuff
      let whichList = -1; // index into lists or -1
      if (line.listLevel) {
        whichList = lists.length;
        for (let j = lists.length - 1; j >= 0; j--) {
          if (line.listLevel <= lists[j][0]) {
            whichList = j;
          }
        }
      }

      // means we are on a deeper level of indentation than the
      // previous line
      if (whichList >= lists.length) {
        lists.push([line.listLevel, line.listTypeName]);
      }

      if (line.listTypeName === "number") {
        pieces.push(
          `\n${new Array(line.listLevel * 4).join(" ")}1. `,
          lineContent || "\n"
        ); // problem here
      } else {
        pieces.push(
          `\n${new Array(line.listLevel * 4).join(" ")}* `,
          lineContent || "\n"
        ); // problem here
      }
    } else {
      // outside any list
      const context = {
        line,
        lineContent,
        apool,
        attribLine: attribLines[i],
        text: textLines[i],
      };

      lineContent = getLineMarkdownForExport(context);
      pieces.push("\n", lineContent, "\n");
    }
  }

  return pieces.join("");
};

// 参考 getLineHTMLForExport 的实现，返回自定义的 Markdown 内容
function getLineMarkdownForExport(context) {
  const img = analyzeLineForTag(context.attribLine, context.apool, "img");
  const customImg = analyzeLineForTag(
    context.attribLine,
    context.apool,
    "customImg"
  );

  if (img) {
    return `![](${img})`;
  }

  if (customImg) {
    return `![](${customImg})`;
  }

  return context.lineContent;
}

function analyzeLineForTag(alineAttrs, apool, tag) {
  let result = null;

  if (alineAttrs) {
    const opIter = Changeset.opIterator(alineAttrs);
    if (opIter.hasNext()) {
      const op = opIter.next();
      result = Changeset.opAttributeValue(op, tag, apool);
    }
  }

  return result;
}

const _analyzeLine = (text, aline, apool) => {
  const line = {};

  // identify list
  let lineMarker = 0;
  line.listLevel = 0;
  if (aline) {
    const opIter = Changeset.opIterator(aline);
    if (opIter.hasNext()) {
      let listType = Changeset.opAttributeValue(opIter.next(), "list", apool);
      if (listType) {
        lineMarker = 1;
        listType = /([a-z]+)([12345678])/.exec(listType);
        if (listType) {
          /* eslint-disable-next-line prefer-destructuring */
          line.listTypeName = listType[1];
          line.listLevel = Number(listType[2]);
        }
      }
    }
  }
  if (lineMarker) {
    line.text = text.substring(1);
    line.aline = Changeset.subattribution(aline, 1);
  } else {
    line.text = text;
    line.aline = aline;
  }

  return line;
};

const getPadMarkdown = async (pad, revNum) => {
  const atext =
    revNum == null ? pad.atext : await pad.getInternalRevisionAText(revNum);

  return getMarkdownFromAtext(pad, atext);
};

const formatMarkdown = markdown => {
  return markdown
    .split("\n")
    .map(e => {
      /**
       * 格式化 list 缩进
       */
      if (e.trim().startsWith("- ")) {
        const text = e.trim();

        if (text.includes("([")) {
          return correctLink(text);
        }

        return text;
      }

      if (e.trim().startsWith("* -")) {
        return e.trim().replace("* -", "-");
      }

      // 解决链接嵌套问题
      if (e.startsWith("### ")) {
        return `### ${correctLink(e.split("### ").pop())}`;
      }

      if (e.includes("([")) {
        return correctLink(e);
      }

      return e;
    })
    .join("\n");
};

module.exports = async function getPadMarkdownDocument(padId, revNum) {
  let res = await getPadMarkdown(await padManager.getPad(padId), revNum);

  res = formatMarkdown(res);

  return res;
};

// copied from ACE
const _REGEX_WORDCHAR = new RegExp(
  [
    "[",
    "\u0030-\u0039",
    "\u0041-\u005A",
    "\u0061-\u007A",
    "\u00C0-\u00D6",
    "\u00D8-\u00F6",
    "\u00F8-\u00FF",
    "\u0100-\u1FFF",
    "\u3040-\u9FFF",
    "\uF900-\uFDFF",
    "\uFE70-\uFEFE",
    "\uFF10-\uFF19",
    "\uFF21-\uFF3A",
    "\uFF41-\uFF5A",
    "\uFF66-\uFFDC",
    "]",
  ].join("")
);
const _REGEX_URLCHAR = new RegExp(
  `([-:@a-zA-Z0-9_.,~%+/\\?=&#;()$]|${_REGEX_WORDCHAR.source})`
);
const _REGEX_URL = new RegExp(
  "(?:(?:https?|s?ftp|ftps|file|smb|afp|nfs|(x-)?man|gopher|txmt)://|mailto:)" +
    `${_REGEX_URLCHAR.source}*(?![:.,;])${_REGEX_URLCHAR.source}`,
  "g"
);
// returns null if no URLs, or [[startIndex1, url1], [startIndex2, url2], ...]
const _findURLs = text => {
  _REGEX_URL.lastIndex = 0;
  let urls = null;
  let execResult;
  // eslint-disable-next-line no-cond-assign
  while ((execResult = _REGEX_URL.exec(text))) {
    urls = urls || [];
    const startIndex = execResult.index;
    const url = execResult[0];
    urls.push([startIndex, url]);
  }
  return urls;
};

</details>

渲染隔离与污染治理

在多渠道发布时，marked.use() 会污染全局实例。如果渠道 A 需要 iframe 视频，渠道 B 只需要链接，必须进行扩展隔离。

// 每次渲染前重置扩展
const { marked } = require("marked");

function renderForChannel(markdown, channelExtensions) {
  // 1. 获取默认扩展
  const defaults = marked.defaults.extensions || {
    renderers: {},
    childTokens: {},
  };

  // 2. 动态合并当前渠道需要的扩展
  const newExtensions = { ...defaults, ...channelExtensions };

  // 3. 强制重置 marked 配置 (HACK)
  marked.setOptions({ extensions: newExtensions });

  return marked.parse(markdown);
}

避坑与经验

链接嵌套修复与清洗

协作编辑时，用户经常造出 [text]([inner](url)) 这种非法 Markdown，导致解析崩溃。

// utils/index.js

/**
 * 修复嵌套链接：[text]([inner](url)) -> [text](url)
 */
function correctLink(markdownText) {
  const pattern = /\[(.+)\]\(\[(.+)\]\((.+)\)\)/g;
  return markdownText.replace(pattern, "[$1]($3)");
}

/**
 * HTML 清洗：移除多余的 P 标签
 */
const removePTag = html => {
  return html.replace(/<p>/g, "").replace(/<\/p>/g, "");
};

/**
 * 链接还原：将 Markdown 链接转为纯文本 (用于生成纯文本目录)
 */
function convertLinksToText(markdownText) {
  return markdownText.replace(/\[([^\]]+)\]\(([^)]+)\)/g, "$1");
}

module.exports = { correctLink, removePTag, convertLinksToText };

Iframe 穿透 (jQuery)

在 Client 端开发时，切记 Ace 运行在嵌套 iframe 中。

// 获取 inner editor 的 body
const $innerBody = $('iframe[name="ace_outer"]')
  .contents()
  .find('iframe[name="ace_inner"]')
  .contents()
  .find("body");

// 绑定事件必须穿透
$innerBody.on("click", "a", function (e) {
  // ...
});

服务端路由：大文件上传限制

如果你在插件中处理图片上传，Express 默认的限制会导致 413 错误。

// 在 hook 'expressCreateServer' 中配置
exports.expressCreateServer = (hookName, args, cb) => {
  const app = args.app;
  // 调大限制到 50mb
  app.use(express.json({ limit: "50mb" }));
  app.use(express.urlencoded({ limit: "50mb", extended: true }));
  cb();
};

多 Mac 设备配置同步方案

Wed, 10 Dec 2025 01:46:00 GMT

前言

过去几年，我的主力机一直是那台 14 英寸的 M1 Pro，虽然也有 dotfiles 仓库，通过手工软链来同步，但充其量只是为了版本控制。

直到我入手了 Mac mini M4，才有了要同步两台设备配置的需求。因为我已经不止一次：在 A 机上装了某个命令行工具，到了 B 机又得重新安装、重新配置……折腾几次后，还是得找一种方案。

我的目标很简单：只要在任意一台机器上安装新软件或修改配置，其他设备可以快速做到 1:1 同步。

核心就两条命令：

离开当前机器前，运行 macup —— 将所有改动备份到仓库
到另一台机器前，执行 macdown —— 从仓库里还原

以下全是细节。

为什么不用这些方案

chezmoi / yadm：有点重
Nix / Home Manager：更重
Mackup + iCloud/Dropbox：确实方便，但更希望放在 Git 里

目前方案

最终核心就三板斧：

Mackup + file_system：所有应用配置都放在 dotfiles 仓库
Brew 的 formula 和 cask 列表，并且有前缀 + 表示需要同步安装
两个脚本：macup 负责备份并更新列表，macdown 负责还原

仓库结构示例如下：

dotfiles/
├── .mackup.cfg
├── mackup/                     # mackup 导出的所有配置
├── mackup/brew-formulae.txt
├── mackup/brew-casks.txt
├── bin/macup → ../mackup-backup.sh
├── bin/macdown → ../mackup-restore.sh
├── bin/xxx                     # 任何可执行文件，会自动软链到 ~/.bin
├── mackup-backup.sh
├── mackup-restore.sh
└── init.sh                     # 新机器第一步运行，自动软链 .mackup.cfg

.mackup.cfg 示例：

[storage]
engine    = file_system
path      = /Users/4ark/projects/dotfiles
directory = mackup
[applications_to_sync]
Bash
Charles
Cursor
claude-code
dig
git-hooks
homebrew
Htop
Itsycal
custom-kitty
nvm
PicGo
Pnpm
ripgrep
SourceTree
yazi
Zsh
Mercurial
p10k
vim
neovim
ssh
starship
[applications_to_ignore]
adium

核心文件说明

mackup/：mackup 导出的配置/偏好，直接放在仓库里版本化
mackup/brew-formulae.txt、mackup/brew-casks.txt：Brew 安装列表，使用 +包名表示需要安装，注释以 # 开头；脚本会去重、排序并保留注释
mackup-backup.sh / bin/macup：备份脚本，负责合并列表、执行 mackup backup 并同步 bin/
mackup-restore.sh / bin/macdown：还原脚本，负责差异预览、执行 mackup restore 并按列表安装软件
init.sh：新机器上第一步运行，为 ~/.mackup.cfg 创建软链

备份流程：macup

收集当前机器的 formula/cask，与列表合并并展示差异
确认后写回 brew-formulae.txt 和 brew-casks.txt
运行 mackup backup --force，将所有配置导出到 mackup/
将仓库的 bin/ 软链到 ~/.bin

恢复流程：macdown

读取 mackup/brew-*.txt，与本机已安装列表对比，并展示「待安装／可移除」项
确认后执行 mackup restore --force，将 mackup/ 中的配置恢复到对应位置
按列表逐个安装缺失的 formula/cask（已安装的会自动跳过）
同步 bin/ 到 ~/.bin（与 macup 流程相同）

OpenSpec 使用心得

Tue, 04 Nov 2025 00:00:00 GMT

一、引言

如果在 2025 年，你还没有在工作中借助 AI，要么你的水平已经超越 AI，要么你就是被 AI 代替的部分。大多数人都不是前者，也不愿成为后者。如何高效、可靠地利用 AI，是每位开发者的必修课。

我个人的探索大致经历了以下几个阶段，从最初的简单补全，到如今的规范驱动开发——OpenSpec。

二、AI 工具演进阶段

洪荒时代：AI 仅作“补全” • 编辑器里集成 Copilot 插件，或者 ChatGPT 网页窗口复制粘贴，AI 只能做最基础的代码补全，效率提升有限。
集成时代：对话式编辑 • Cursor 等工具将聊天窗口直接搬进 IDE，上下文无缝传递，减少复制粘贴的步骤。
增强时代：MCP 协议崛起 • Model Context Protocol 赋予 AI Agent 文件读写、命令执行、API 调用能力，自动化水平大幅跃升。
智能时代：自主驱动 • AI Agent 能理解复杂任务，分解步骤，自主调用工具链完成工作，不再是简单的问答助手，而是智能协作伙伴。

三、现有困境与解决方案

尽管 AI 功能越来越强，但在团队协作中，仍面临几大痛点：

上下文串台：长对话中不同任务相互干扰
信息丢失：超出上下文窗口后，需反复重新说明
难以复用：项目约定无法在新会话中继承

过去，我常让 AI Agent 先输出思路再动手，但每次改动都像黑盒测试，改错了只能重来。

这也是大家遇到的问题，所以最近出现了一系列工具：spec-kit、OpenSpec 等。

OpenSpec 核心思路

“每次改动都是一个提案” • 在动手之前，先形成结构化的 proposal.md，明确 Why / What / How / Impact，我们 Review 通过后再执行。
规范驱动、约定可持久化 • 所有决策、设计、验收标准都以文件形式保存在仓库里，新工具或新同事都能快速“秒懂”项目规范。

通过将项目规范、架构决策、功能需求以结构化文档记录，OpenSpec 保证了上下文一致性、变更可追溯，也让 AI Agent 在任何时刻都能准确执行。

四、角色转变

之前：在微观层面指挥 AI Agent “写这段代码”“改那个函数”
现在：从宏观角度当“产品经理”或“团队 Leader”
1. 我来讲需求
2. AI Agent 起草提案
3. 我 Review 并反馈
4. AI Agent 修改提案
5. 我确认后，AI Agent 执行代码落地

这样一来，我们从指令层的操作者，变成了规范层的把关者，放权给 AI Agent 干更多“脏活累活”。

五、OpenSpec 使用案例

下面以“撰写本篇文章”为例，演示 OpenSpec 的完整流程。

1. 安装 OpenSpec

# 检查 Node.js 版本（需要 >= 20.19.0）
node --version
# v24.11.0

npm install -g @fission-ai/openspec@latest

2. 初始化 OpenSpec

cd my-project
openspec init

选择支持的 AI 工具（如 Claude Code、Cursor 等）
自动生成 openspec/project.md、openspec/AGENTS.md、openspec/specs/、openspec/changes/ 等目录结构

验证初始化成功，只需要执行：

openspec list
# No active changes found.

然后让 AI Agent 帮你完善项目背景：

Populate your project context:
"Please read openspec/project.md and help me fill it out with details about my project, tech stack, and conventions"

3. 创建提案

向 AI Agent 提需求：

“在 src/content/blog 下新建《OpenSpec 使用心得》文章，包含：

引言：为何要拥抱 AI

AI 演进阶段

现有困境与解决方案

OpenSpec 流程

个人实践心得”

AI Agent 自动生成 openspec/changes/complete-openspec-article/proposal.md、tasks.md、相应 specs/。

proposal.md 包含了提案的核心信息：

## Why

现有的 `src/content/blog/2025-11-04-openspec.md` 文章内容不完整，
需要补充完整的内容以完成一篇关于 OpenSpec 使用心得的博客文章。

## What Changes

- 完成博客文章 `src/content/blog/2025-11-04-openspec.md` 的写作
- **保留现有内容**：不删除已有的引言、演进阶段和困境解决方案部分
- **文章要求**：
  - 确保内容准确性
  - AI 工具演进阶段需准确描述
  - 精简整篇文章篇幅...
  - 统一名词使用...

## Impact

- 受影响文件：`src/content/blog/2025-11-04-openspec.md`

tasks.md 列出了详细的实施任务清单：

## 1. 内容创作

- [ ] 1.1 完成第一部分：引言：拥抱 AI 工具
- [ ] 1.2 完成第二部分：AI 工具的演进阶段
  - [ ] 1.2.1 以段落形式描述四个阶段...
- [ ] 1.3 完成第三部分：现有困境与解决方案
- [ ] 1.4 完成第四部分：OpenSpec 的特点与使用流程
  - [ ] 1.4.1 准确介绍 spec-kit 和 OpenSpec 工具...
  - [ ] 1.4.5 使用案例：完成这篇文章提案本身...

specs/blog-content/spec.md 定义了规范要求：

## ADDED Requirements

### Requirement: OpenSpec 使用心得博客文章

博客系统 SHALL 包含一篇完整的关于 OpenSpec 使用心得的文章...

#### Scenario: 文章内容完整性

- **WHEN** 用户访问博客文章页面
- **THEN** 文章应包含所有五个主要部分...

#### Scenario: 文章精炼度

- **WHEN** 文章完成
- **THEN** 应遵循以下原则：
  - 去除所有冗余和重复内容...
  - 使用案例部分需要详细描述...

4. 反复打磨

我在对话中提出细化或优化建议，AI Agent 即刻更新提案，直到内容满足需求，再进入“实施”阶段。

更新提案，介绍完现有的困境，以及 spec-kit 和 openspec 这类工具的优势以后，就要开始一个使用案例，我就以本次我是如何使用 openspec 帮我完成这个提案本身，去写这篇文章。

更新提案，文章里面有几个部分需要调整：

AI 工具的演进阶段，是不是足够准确

精简整篇文章，去除冗余和重复内容

5. 实施与归档

跟 AI Agent 说：

实施这个提案

它会自动帮你执行这个指令：openspec apply complete-openspec-article

归档这个提案

对应这个指令：openspec archive complete-openspec-article --yes

提案及规范文件被归档到 openspec/changes/archive/2025-11-04-complete-openspec-article/，形成完整可追溯的记录。

六、个人实践心得

我只需记住如何初始化 OpenSpec，具体命令让 AI Agent 自动完成。
项目规范文件是最宝贵的资产：新工具、新同事都能无缝衔接，消除了流程断层。

uni-app 多端组件属性与样式透传行为一致性实践

Tue, 28 Oct 2025 00:00:00 GMT

现状分析

起因是一个以微信小程序为主开发的 uni-app 应用，在编译到 App 端后，出现了各种样式问题。

为了更好地理解这个问题，让我们创建一个最小化的示例项目：

pnpm create uni@latest # 什么都不加

一个经典的嵌套组件，用于测试三个端组件样式表现：

这里可以看到，每个组件都开启了 style scoped，此时三个端的表现是一致的，没有任何问题：

然而，在实际开发中，我们经常会遇到这样一种情况：由于启用了 style scoped，往往会倾向于使用简单的 class 命名，比如大量使用 container 这样的通用类名。让我们看一个具体示例：

在这种情况下，三个端的表现会出现明显的差异：

这是 bug？先说结论，这是 Vue 的 feature：

使用 scoped 后，父组件的样式将不会渗透到子组件中。不过，子组件的根节点会同时被父组件的作用域样式和子组件的作用域样式影响。这样设计是为了让父组件可以从布局的角度出发，调整其子组件根元素的样式。

可前面说了，我们是以微信小程序为主进行开发，看到这种情况还是会非常懵逼。

所以，这就不得不先看一下 uni-app 在不同端是如何实现样式隔离的。

样式隔离

App 端的实现方式其实与我们熟悉的 Vue 浏览器端机制一样：它们都是通过为每个标签动态添加 [data-v-scopeId] 属性来实现样式的作用域隔离。

而在微信小程序端，由于小程序的 CSS 不支持属性选择器，uni-app 采用了一种变通方案：为每个标签添加带有 [data-v-scopeId] 的 class 来实现隔离效果。

下面这张图可以帮助我们直观地理解三个端的 HTML 结构差异：

这里我们可以留意到，子组件的根元素会附带上父组件的 scopeId，所以父组件可以影响它的样式。

而在微信小程序，因为多了一层 <components/comp-child> 这样的东西，scopeId 并不在真正的组件根元素，所以它的表现会与其余两个端不一致。

解决方案

因为我们还是希望 App 端可以与微信小程序端的表现保持一致，此时有两条路可以走：

不要这个 feature
保留这个 feature

反正我们的目的只有一个：减少开发时的心智负担。

方案一

对于第一条路子，实现方式非常简单粗暴，既然 Vue 只针对单根组件会有这个 feature，那我们强制所有组件变成多根节点就好了，简单说就是实现一个 Vite 插件，利用 transform 钩子往 Vue 组件顶层插入一个 <Fragment /> 元素，这样立马可以让 App 和 H5 的表现与微信小程序保持一致。

然而这样会损失 Vue 特地带来的便利，正如官方文档所说，这个 feature 会无形中减少很多布局实现上的麻烦，因此最终还是决定让微信小程序能够对齐另外两端的实现。

方案二

根据前面的 HTML 结构图可以看到，微信小程序主要是因为多了一层节点(虚拟节点)，是不是只要把它干掉就好了？

说干就干，在 uni-app 文档中指出，只要在 Vue 组件中配置 virtualHost: true 并且配合 mergeVirtualHostAttributes 即可合并组件虚拟节点外层属性：

然而，此时 HTML 结构中 scopeId 虽然已经放到组件的根节点上，但样式表现仍然没有发生变化，这是因为 uni-app 默认给微信小程序组件设置的样式隔离是 apply-shared，还需要把 styleIsolation 改成 shared 才能使其影响其它组件。

对应到本文例子就是要给 comp-parent.vue 添加：

defineOptions({
  options: {
    virtualHost: true,
    styleIsolation: "shared", // [!code ++]
  },
});

修改以后，微信小程序上的表现已经完全与其余两端一致：

这个方案的好处在于，可以让微信小程序组件无限接近 Vue 组件的表现，除了样式透传，还包括可以属性透传，比如 id、class、style、v-show 等。

我写了一个 Vite 插件自动注入这个 virtualHost: true 配置，有兴趣可以看：https://github.com/gd4Ark/vite-plugin-uni-virtual-host

页面样式优先级

其实到这里三端表现已经基本一致，但在微信小程序还有一些细微的差别，主要问题是出在样式优先级。

还是上面那个例子，在页面级组件去覆写子组件样式：

由于微信小程序加载 css 顺序的问题，表现与其余两端不一致：

这问题看起来是无解的，只能手动识别这种情况，并添加 !important 提高样式权重。

uni-app 与原生小程序混合开发方案

Wed, 15 Oct 2025 00:00:00 GMT

前言

在过去两年里，我接手维护了多个原生语法开发的微信小程序项目。由于新项目均采用 uni-app 开发，这些原生项目无法复用在 uni-app 生态积累的工具库、业务组件和 Hooks 等基础设施。

为了解决技术栈割裂的问题，探索并实践了多种混合开发方案，本文将分享相关的技术方案与实践经验。

项目现状分析

或许会好奇，为什么不直接选择用 uni-app 对项目进行全面重构呢？

其实，除了精力有限，更重要的原因在于：

线上存在众多活动页，这些页面相对独立且变动频率低，重构它们的收益并不高
项目已有功能较为复杂，后续开发需求主要是新增页面，而不是对现有功能进行大规模改造

综上，采用混合开发的渐进式方案，无疑更加高效且具性价比。目前项目主要面临两类需求场景：

项目主框架用 uni-app 重构，但需要继续复用原有的众多子页面（如各类活动页）
老项目已趋于稳定，仅需在其基础上新增某些复杂且相对独立的模块

uni-app 官方文档提供了几种与原生小程序混合开发的技术方案：

方式 1：把原生小程序转换为 uni-app 源码。有各种转换工具
方式 2：把原生小程序的代码变成小程序组件，进而整合到 uni-app 项目下
方式 3：原生开发的小程序仍保留，部分新功能使用 uni-app 开发

然而，这些方案无法直接满足目前的场景。鉴于涉及的项目较多，决定设计一套更具通用性和可扩展性的混合开发方案，以方便快速适配应用。

uni-app 项目复用原生小程序页面

这种方案核心思路是：将原生小程序页面搬到 uni-app 项目的构建产物中，并注册页面。

为了提升开发效率，需要将这个过程自动化。所以，开发 Vite 插件来做这件事情最适合不过了。

假设项目结构如下：

.
├── src/                # uni-app 项目主目录
│   ├── pages/          # uni-app 页面
│   ├── components/     # uni-app 组件
│   └── ...
├── miniprogram/        # 原生微信小程序代码目录
│   ├── components/     # 需要复用的原生组件
│   ├── pages/          # 需要复用的原生页面
│   └── ...
├── vite.config.ts      # Vite 配置文件
└── ...

该 Vite 插件需要实现以下核心功能：

构建阶段：将 miniprogram 目录中的目标文件自动同步到 dist 构建目录
资源管理：将原生项目的公共模块（如工具库、依赖包等）统一迁移至独立的 shared 命名空间，并自动更新相关模块的引用路径，避免与 uni-app 构建产物发生冲突
配置更新：自动维护 app.json 配置文件，处理页面路由注册和全局组件声明
开发体验：实现文件系统监听，当检测到 miniprogram 目录的文件变更时，自动触发增量构建

伪代码实现，大概流程就是这样：

function uniWxCopyPlugin(options) {
  let publicBasePath = '' // Vite 的 base 配置
  let configPath = ''     // 最终输出目录
  let isDev = false      // 是否开发环境

  return {
    name: 'vite-plugin-uni-wx-copy',

    // Vite 配置解析完成后执行
    configResolved(config) {
      // 判断是否为微信小程序环境
      if (config.define['process.env.UNI_PLATFORM'] !== '"mp-weixin"') {
        return
      }

      publicBasePath = config.base
      isDev = config.mode === 'development'
    },

    // 构建完成后执行
    writeBundle(options) {
      const p = options.dir // 构建输出目录

      // 如果没有输出目录或 base 配置，则不执行
      if (!p || !publicBasePath) {
        return
      }

      // 计算最终输出目录
      configPath = resolve(publicBasePath, p)

      // 1. 复制原生组件到共享目录
      copy(
        'miniprogram/components' ->
        configPath + '/shared/components'
      )

      // 2. 复制页面
      copy(
        'miniprogram/pages/index' ->
        configPath + '/pages/index'
      )

      // 3. 替换页面中的组件引用路径
      replace(
        file: configPath + '/pages/**/*.json',
        from: '/components/',
        to: '/shared/components/'
      )

      // 4. 开发模式下监听文件变化
      if (isDev) {
        watch('miniprogram/**/*', (changedFile) => {
          if (changedFile.includes('pages/')) {
            copy(
              changedFile ->
              configPath + '/' + changedFile
            )
          }
          else if (changedFile.includes('components/')) {
            copy(
              changedFile ->
              configPath + '/shared/' + changedFile
            )
            replace(
              file: configPath + '/pages/**/*.json',
              from: '/components/',
              to: '/shared/components/'
            )
          }
        })
      }
    }
  }
}

有了这个插件，在每个项目通过配置，就能快速实现混合开发：

import uni from "@dcloudio/vite-plugin-uni";
import { defineConfig } from "vite";
import uniWxCopy from "vite-plugin-uni-wx-copy";

export default defineConfig({
  plugins: [
    uni(),
    uniWxCopy({
      rootDir: "../miniprogram",
      // 复制共享资源
      copy: [
        {
          sources: ["components", "static", "utils"],
          dest: "shared/",
          shared: true,
        },
      ],
      // 主包页面
      pages: ["pages/index", "pages/page1", "pages/page2"],
      // 分包配置
      subPackages: [
        {
          root: "subpackages",
          pages: ["detail"],
        },
      ],
      // 重写 app.json 以添加全局组件
      rewrite: [
        {
          file: "app.json",
          write: code => {
            const appJson = JSON.parse(code);
            appJson.usingComponents = {
              ...appJson.usingComponents,
              "app-btn": "/shared/components/app-btn/app-btn",
            };
            return JSON.stringify(appJson, null, 2);
          },
        },
      ],
    }),
  ],
});

还需要解决一个关键问题：原生小程序页面与 uni-app 主体之间的状态共享，包括环境配置、用户信息等运行时数据。

由于不同项目的业务场景各不相同，这里采用了一种可定制的状态共享方案：

利用小程序全局实例 getApp() 作为跨技术栈的通信桥梁，在 uni-app 项目中实现状态管理和更新的核心逻辑
在构建过程中，通过字符串匹配，将原生项目中的方法替换成 getApp() 提供的统一接口

举个例子，将原本的鉴权方法改成通过 getApp 使用 uni-app 项目提供的：

// auth.getUserInfo( -> auth.getApp().getUserInfo(
{
  replaceRules: {
    from: /auth.getUserInfo\(/g,
    to: 'getApp().getUserInfo(',
    files: [
      ...pages.map(page => path.join(configPath, page, '**/*.js')),
      ...shared.sources.map(dir => path.join(configPath, shared.dest, dir, '**/*.js')),
    ],
  },
}

再举个例子，动态修改原生项目的开发环境：

{
  rewrite: [
    {
      file: "shared/config/index.js",
      write: code => {
        // eslint-disable-next-line no-param-reassign
        code = code.replace(
          /export const DEV =(.+)/,
          `export const DEV = ${mode === "development" ? "true" : "false"}`
        );

        return code;
      },
    },
  ];
}

有兴趣可以看看这个插件：vite-plugin-uni-wx-copy

uni-app 项目集成到原生小程序

这种方案核心思路是：将 uni-app 项目的构建产物集成到原生小程序项目中，并注册页面。

没错，就是与上面的方案反过来，这也是得益于 uni-app 项目提供了一个打包方式：混合分包。

简单说就是将一个 uni-app 项目打包成小程序的一个分包，满足以下场景：

既可以实现将功能集成到现有的小程序项目中，同时支持分发到 APP、H5 等
微信小程序单个分包限制为 2M，可按需拆分多个分包，且不影响其它平台分发

假设目录结构如下：

.
├── miniprogram/          # 原生微信小程序项目目录
│   ├── app.js
│   ├── app.json
│   └── ...
└── uni-app-project/     # uni-app 项目目录
    ├── src/
    ├── vite.config.ts
    └── ...

在 uni-app 项目的 package.json 中配置分包构建命令（根据情况决定是否需要多个分包）：

{
  "scripts": {
    "dev": "run-p 'dev:**'",
    "build": "run-p 'build:**'",
    "dev:pkg-a": "uni -p pkg-a --subpackage=pkg-a",
    "build:pkg-a": "uni build -p pkg-a --subpackage=pkg-a",
    "dev:pkg-b": "uni -p pkg-b --subpackage=pkg-b",
    "build:pkg-b": "uni build -p pkg-b --subpackage=pkg-b"
  },
  "uni-app": {
    "scripts": {
      "pkg-a": {
        "title": "pkg-a",
        "env": {
          "UNI_PLATFORM": "mp-weixin"
        },
        "define": {
          "MP-PKG-A": true
        }
      },
      "pkg-b": {
        "title": "pkg-b",
        "env": {
          "UNI_PLATFORM": "mp-weixin"
        },
        "define": {
          "MP-PKG-B": true
        }
      }
    }
  }
}

在 uni-app 项目的 pages.json 中使用条件编译配置分包页面：

{
  "pages": [
    // #ifdef MP-PKG-A
    {
      "path": "pages/index/index"
    },
    // #endif
    // #ifdef MP-PKG-B
    {
      "path": "pages/detail/index"
    }
    // #endif
  ]
}

该 Vite 插件需要实现以下核心功能：

构建阶段：将 uni-app 的构建产物放到原生小程序项目中
开发体验：uni-app 热更新时，更新差异部分

伪代码实现，大概流程就是这样：

function uniSubpackageCopyPlugin(options) {
  return {
    name: "vite-plugin-uni-subpackage-copy",
    // 在其他插件之后执行
    enforce: "post",

    // 构建完成后执行
    async writeBundle(output) {
      // 1. 如果配置了重写规则，先处理文件重写
      if (options.rewrite) {
        for (const rule of options.rewrite) {
          // 读取文件
          const content = readFile(rule.file);
          // 使用重写函数处理内容
          const newContent = rule.write(content);
          // 写入新内容
          writeFile(rule.file, newContent);
        }
      }

      // 2. 使用 rsync 将分包文件从 uni-app 构建目录同步到原生项目
      rsync({
        from: options.subpackageDir, // uni-app 分包构建目录
        to: options.rootDir, // 原生项目目录
        // 保持文件属性，递归同步，压缩传输
        flags: "avz",
        // 删除目标目录中源目录没有的文件
        delete: true,
      });
    },
  };
}

在 uni-app 项目的 vite.config.ts 中配置插件：

import uni from "@dcloudio/vite-plugin-uni";
import { defineConfig } from "vite";
import uniSubpackageCopy from "vite-plugin-uni-subpackage-copy";

export default defineConfig({
  plugins: [
    uni(),
    process.env.UNI_PLATFORM === "mp-weixin" &&
      uniSubpackageCopy({
        rootDir: "../miniprogram",
        subpackageDir: process.env.UNI_SUBPACKAGE,
      }),
  ],
});

有兴趣可以看看这个插件：vite-plugin-uni-subpackage-copy

我如何自己实现 lint-staged

Mon, 13 Oct 2025 00:00:00 GMT

前言

都 2025 年了还在聊 lint-staged？确实有点复古。但最近实在闲得慌，博客都快长草了，索性把过去几年踩过的坑和折腾过的轮子翻出来炒冷饭。接下来会陆续更新一系列文章，就当是给自己这几年的搬砖生涯做个总结。

为什么要自己实现 lint-staged？

说来惭愧，我司用的不是 git，而是 Mercurial (hg) 这个「冷门」版本控制工具。所以很自然地，git 生态下的各种神器都用不了。2022 年写过一篇《Hg hooks 实践历程》，主要就是给 hg 造了个 husky 轮子，结果被领导看上了，在公司内推广使用。既然都做到这份上了，lint-staged 自然也被提上了日程。

简单来说，lint-staged 就是专门处理暂存区（staged）文件的格式化和 lint 操作。这样做有两个好处：一是速度快，二是不会被那些还没提交的本地改动搞出来的 lint 错误打断提交。

但问题来了，hg 压根就没有暂存区这玩意儿！这就是我实现 lint-staged 时遇到的最大挑战。

实现思路

先回忆一下 lint-staged 的标准配置：

{
  "scripts": {
    "lint-staged": "lint-staged"
  },
  "lint-staged": {
    "**/*.{js,vue}": ["eslint --cache --fix", "pnpm dts"],
    "**/*.{css,vue}": "stylelint --cache --fix",
    "**/*.{json,d.ts,md}": "prettier --write"
  }
}

然后在 pre-commit 钩子里执行：

# .husky/pre-commit

npx lint-staged

标准流程是这样的：

在 pre-commit 阶段执行 lint-staged
通过 git 命令获取暂存区的文件列表，对这些文件按配置执行各种命令
把产生的文件改动重新加到暂存区，合并到本次提交

但 hg 没有暂存区，没法像 git 那样直接获取文件列表，只能另辟蹊径。虽然官方 lint-staged 在 pre-commit 阶段执行，但在 hg 中我们可以改到 pretxncommit 阶段，用 hg export tip --template "{file_adds} {file_mods}" 命令获取本次提交涉及的文件列表。

lint-staged 的操作会改动文件，需要把产生的改动合并到本次提交中。在 hg 里可以用 (HUSKY=0 hg commit $files --amend -m "$commit_message") >/dev/null 2>&1 命令把最新改动合并到本次提交。

PS：这里需要 HUSKY=0 是因为本次提交不需要再经过 lint-staged，不然就会死循环。

到这里其实已经可以做到官方 lint-staged 的核心功能，基本够用了。但我们还有个额外需求：有些项目会对 .js 文件执行 pnpm dts 操作，这会产生新文件或删除文件，我们希望把这些 lint-staged 操作导致的文件改动也合并到本次提交中。

举个例子，我们有 a.js，经过 pnpm dts 后会产生 types/a.d.ts，我们想把这个文件也合并到提交中。所以设计了一个硬编码命令 hg commit：

"lint-staged": {
   "**/*.{js,vue}": [
     "eslint --fix",
     "pnpm dts",
     "hg commit"
   ],
},

当遇到 hg commit 时，就获取最新的文件改动列表，与之前拿到的文件改动列表做 diff，差异部分就是本次操作产生的改动。把这部分差异存到临时文件里，附加到 $files 中，就能实现想要的效果。

核心代码

最后附上核心实现，首先是 lint-staged.js：

#!/usr/bin/env node

/* eslint-disable no-console,no-await-in-loop */

const fs = require("fs");
const { exec, execSync: _execSync } = require("child_process");
const path = require("path");

const glob = require("glob");

const cwd = process.cwd();

// 获取 hg 仓库根目录路径
const ROOT_PATH = execSync("hg root");
const PACKAGE_JSON_PATH = path.join(cwd, "package.json");

// 临时文件路径，用于存储 lint-staged 操作产生的文件改动
const LINT_STAGED_MODIFIED_PATH = path.join(
  ROOT_PATH,
  ".hghusky/_",
  "LINT_STAGED_MODIFIED"
);

// 硬编码的特殊命令，用于触发文件改动检测
const COMMIT_COMMAND = "hg commit";

main();

async function main() {
  try {
    // 组合函数：读取配置 -> 生成命令 -> 执行命令
    const tasks = compose(
      getLintStagedConfig,
      generateCommands,
      executeCommands
    );

    await tasks();
  } catch (error) {
    console.error(error);
    process.exit(1);
  }

  process.exit(0);
}

/**
 * 从 package.json 中读取 lint-staged 配置
 */
function getLintStagedConfig() {
  const packageJsonContent = fs.readFileSync(PACKAGE_JSON_PATH, "utf-8");
  const packageJson = JSON.parse(packageJsonContent);
  const lintStagedConfig = packageJson["lint-staged"];

  if (!lintStagedConfig) {
    throw new Error("No lint-staged config found");
  }

  return lintStagedConfig;
}

/**
 * 根据配置生成需要执行的命令
 * 核心逻辑：匹配本次提交的文件与配置的 glob 模式
 */
function generateCommands(config) {
  // 获取本次提交涉及的文件列表（新增和修改的文件）
  const committedFiles = execSync(
    'hg export tip --template "{file_adds} {file_mods}"'
  ).split(" ");
  const commands = [];

  Object.entries(config).forEach(([pattern, command]) => {
    // 1. 使用 glob 匹配所有符合模式的文件
    // 2. 转换为相对于仓库根目录的路径
    // 3. 过滤出本次提交涉及的文件
    // 4. 转换为相对于当前工作目录的路径
    const matchedFiles = glob
      .sync(pattern, { nodir: true })
      .map(file => path.relative(ROOT_PATH, path.resolve(cwd, file)))
      .filter(file => committedFiles.includes(file))
      .map(file => path.relative(cwd, path.resolve(ROOT_PATH, file)))
      .join(" ");

    if (matchedFiles) {
      commands.push({ command, files: matchedFiles });
    }
  });

  return commands;
}

/**
 * 执行生成的命令列表
 * 关键特性：支持检测命令执行前后的文件变化
 */
async function executeCommands(commands) {
  await Promise.all(
    commands.map(async item => {
      if (!item.files.length) return;

      // 如果命令是数组（包含多个子命令）
      if (Array.isArray(item.command)) {
        // 检查是否包含特殊的 hg commit 命令
        const needCommit = item.command.find(cmd => cmd === COMMIT_COMMAND);

        // 如果需要检测文件变化，先记录当前的文件状态
        const prevModifyFiles = needCommit ? getModifyFiles() : [];

        // 依次执行每个子命令
        for (const subCommand of item.command) {
          if (subCommand === COMMIT_COMMAND) {
            // 遇到 hg commit 命令时，计算文件变化
            const afterModifyFiles = diff(getModifyFiles(), prevModifyFiles);

            // 如果有新产生的文件改动，写入临时文件
            if (afterModifyFiles.length) {
              fs.writeFileSync(
                LINT_STAGED_MODIFIED_PATH,
                afterModifyFiles.join(" ")
              );
            }
          } else {
            await executeCommand(`${subCommand} ${item.files}`);
          }
        }

        return;
      }

      await executeCommand(`${item.command} ${item.files}`);
    })
  );
}

function executeCommand(commandWithFiles) {
  return new Promise(resolve => {
    console.log(`[lint-staged] execute: ${commandWithFiles}`);
    const child = exec(commandWithFiles, (error, _stdout, stderr) => {
      if (error) {
        console.warn(stderr);
        process.exit(1);
      } else {
        resolve();
      }
    });

    // 将子进程的输出重定向到当前进程
    child.stderr.pipe(process.stderr);
    child.stdout.pipe(process.stdout);
  });
}

// eslint-disable-next-line consistent-return
function execSync(command) {
  try {
    const result = _execSync(command, { encoding: "utf-8" });

    return result.trim();
  } catch (error) {
    console.error(`[lint-staged] execute ${command} error: ${error}`);

    process.exit(1);
  }
}

function compose(...functions) {
  return async () => {
    let result;
    for (const func of functions) {
      result = await func(result);
    }

    return result;
  };
}

/**
 * 获取当前工作目录中所有修改过的文件列表
 * 用于检测 lint-staged 操作产生的文件变化
 */
function getModifyFiles() {
  return execSync("hg status | sort")
    .split("\n")
    .map(line => line.replace(/^.*?\s/, ""));
}

function diff(array1, array2) {
  return array1.filter(item => !array2.includes(item));
}

这里最关键的就是会在遇到 hg commit 命令的时候，产生一个临时文件 LINT_STAGED_MODIFIED_PATH，它就是本次操作改动的文件列表，然后在 commit 阶段将其附加到 $files 合并到本次提交：

#!/bin/bash

HUSKY_DIR='.hghusky'

# 在上级目录的 commit 执行之前，先做一些初始化工作
commit_message=$(hg tip --template '{desc}')

# 将 lint-staged 产生的变更重新添加到当前 commit 中
function mergeAutoFixed2Commit() {
  if [ ! -f "$HUSKY_DIR/pretxncommit" ]; then
    exit 0
  fi

  skipLint

  files=$(hg export tip --template '{files}')

  # 提交 lint-staged 阶段改动的文件
  LINT_STAGED_MODIFIED_PATH="$HUSKY_DIR/_/LINT_STAGED_MODIFIED"
  if [ -f "$LINT_STAGED_MODIFIED_PATH" ]; then
    modified_files=$(cat "$LINT_STAGED_MODIFIED_PATH")
    files="$files $modified_files"

    rm "$LINT_STAGED_MODIFIED_PATH"
  fi

  set +e
  # shellcheck disable=SC2086
  hg addremove $modified_files
  # shellcheck disable=SC2086
  (HUSKY=0 hg commit $files --amend -m "$commit_message") >/dev/null 2>&1
  set -e
}

if [ -f "$HUSKY_DIR/pretxncommit" ]; then
  mergeAutoFixed2Commit
fi

2024 年终总结

Tue, 31 Dec 2024 00:00:00 GMT

前言

“今年是过去十年最糟糕的一年，但可能是未来十年最好的一年。”在 2019 年，这句带着预言性质的话，当时我还未完全理解其深意。但如今站在 2024 年回望，竟显得如此贴切，甚至更具分量。

在经济下行、行业调整的大环境下，谁的日子都不好过。许多公司都在减员，失业的人也越来越多，这并非个人努力所能轻易改变，而是整个行业，整个社会都在经历一段艰难时期。

于我个人而言，今年似乎是凝固的一年，各方面都乏善可陈，几乎没有任何的改变。然而，在这充满不确定性的环境下，或许这种“不变”本身竟也未尝不是一种幸运。它意味着，尽管没有迎来期待中的跃升，但至少也没有滑向更深的低谷，还能维持着现有的状态。

放眼四周，或许这也是许多普通人共同的感受，我们虽不能左右大势，但至少可以努力过好自己的生活，在力所能及的范围内做出改变。我深知自己无力也无意去探讨那些宏大的社会命题，眼下更应关注的是如何在不确定的环境中自洽地生活，努力地生长。所以，我选择记录自己，因为“记录”，本身就是对抗时间流逝、对抗虚无的一种方式，即使是再平凡不过的一年，也值得被认真对待、被仔细书写。

因此，我将从以下几个方面，记录下属于我的 2024 年。

工作

首先从工作方面说起。今年我接触到了不少新的挑战和领域，这无疑是一件好事。毕竟，我从来不是、也不希望自己成为那种“一年经验用十年”的人，持续学习和成长才是我所追求的。然而，大环境的浪潮也波及到了公司，陆陆续续的裁员消息让人倍感无奈。身处其中，除了更加努力地做好本职工作，不断提升自身价值，似乎也没有更好的应对之法。

即便如此，今年在工作中依然遇到了一件颇有意思的事，也算是一种调剂。一位同事向我询问有什么好用的工具推荐，或许这只是他不经意的一问，但却触动了我。那一刻，我意识到自己在他人眼中，或许已然成为了一个善于利用工具提升效率的人，这让我既有些许得意，又感到一丝惭愧。因为被这突如其来的一问，我竟一时语塞，只能随便找了个理由应付过去。但事后，我暗下决心，一定要专门写一篇文章，好好整理一下我正在使用的工具。这不仅仅是为了回应那位同事的期待，更是为了对自己过去一段时间工具使用情况的梳理和总结，因此有了这篇文章《2024 年使用的工具从 A 到 Z》。

其实，在日复一日的工作中，类似这样的小事还有很多，若用心留意，便能从中汲取养分。一份工作做得久了，难免会陷入枯燥的循环，热情也随之消磨殆尽。因此，我们需要主动去寻找一些能够点燃内心、让自己持续获得满足感的事情。这种满足感并非仅仅来源于完成日常的任务，而是源于内心的充盈，源于那些真正让自己觉得有意义、有价值，能让自己或他人变得更好的事情。

学习

接下来本应谈谈学习，但老实说，今年我在工作之外的时间里，并没有进行严格意义上的学习。不过，我也并非完全虚度，而是将精力投入到了各种“折腾”之中。而谁又能说，这些看似“不务正业”的折腾，不是一种另类的学习方式呢？

电子族谱

今年清明，回乡扫墓。在老家里，长辈们聊着祖辈们的往事，我翻阅着那本泛黄的族谱，一个念头跃入脑海：我们这一辈，又有几人真正看过族谱，了解祖先的生平呢？纸质族谱固然珍贵，但往往被束之高阁，查阅与补充皆有不便。时代在变，电子族谱或许才是传承家族记忆的更好选择。

我希望能用自己的方式为家族做些什么，这既是出于对历史的热爱，也是对先祖的一种尊敬。毕竟每个人百年之后不过黄土一抔，我们年年祭拜的先祖，又有多少后人能道出他们的姓名和生平？历史的魅力，正在于它记录了那些鲜活的生命，让逝者不至于完全湮没在时间的尘埃中。将族谱电子化，为每位祖先建立生平简介，或许能激发年轻一辈的兴趣。纵然无法让每个人都产生共鸣，至少也遂了我个人的心愿。我更希望，将来我的后代能够通过这份电子族谱，了解自己的血脉源流，知道自己从何处来。

当然，我无法像司马迁那样为每位祖先著书立传。他们世代为农，平凡一生，能记录的或许只有姓名、生卒、婚配和安葬地。然而，这些看似简单的信息，串联起来，便构成了家族的历史长卷，也证明了他们曾经鲜活地存在过。在整理这些信息的过程中，我自身也受益匪浅，了解到了更多姓氏起源、堂号分布、乃至寻根溯源的知识，更对族谱编修有了更深的体会。这并非简单的信息录入，为了撰写先祖的生平，我需要对不同来源的记载进行仔细的考究和推理，辨别真伪，有时还需要翻阅当时的县志，去还原那时的社会风貌。或许有些先祖的生卒年份和源流已不可考，但我仍秉持“成功不必在我”的信念，尽己所能记录现有资料，留待后人去完善。这段经历，让我初窥了历史学家们为研究一个人物生卒年月所做的大量工作，体会到那种求真务实的严谨，也更加坚定了我做好这份电子族谱的决心。

电子阳痿

“电子阳痿”常被用来形容对电子游戏失去兴趣。对我来说，游戏的“阳痿”早已开始。年少时，我曾是个“网瘾少年”，逃课去网吧也是常事。不知何时起，游戏的热情悄然消退。还记得刚工作时，同事们休息时间捧着 Switch 酣战，而我却提不起丝毫兴趣。

与游戏相对的，是我曾经对折腾电子产品的狂热。如果说游戏是我年少时的一项爱好，那么刷机则是另一项。小时候电子设备有限，手机便成了我最好的玩具。为了研究刷机，我废寝忘食，线刷、卡刷、救砖，这些身边人闻所未闻的词汇，于我却充满魔力。后来，能接触的电子产品多了，从手机、电脑到路由器，只要能刷系统的，我都乐此不疲地折腾一遍。

这其中，最让我印象深刻的是在学校参加市级比赛时的一段经历。其中需要练习配置思科网络设备，出于“折腾”的本能，我给工作室的一台无线 AP 升级了固件，结果不幸变砖，无法正常启动。当时的我吓得不轻，担心被开除，于是没有告诉老师。还记得那是一个周五的下午，放学后的我怀着无比沉重的心情回了家。整个周末，我都茶饭不思，泡在论坛里寻找解决方案，可谓“寝食难安”。所幸皇天不负有心人，终于找到了救砖的方法。一回学校，我便第一时间奔向工作室，成功救活了那台 AP。相信每个喜欢折腾的人，都经历过类似的苦与乐。“折腾”的过程总是充满挑战，甚至伴随着痛苦的“翻车”，但当你最终解决问题时，那种成功的喜悦和满足感也无与伦比。

然而近两年，这份对电子产品的热情也逐渐冷却。曾经热衷的钻研和尝试，如今都变得兴致索然。我并非完全不再折腾，只是和年少时相比，少了很多热情。就拿之前折腾的黑群晖来说，硬盘坏了好久，我也一直没去管它。我曾一度认为，继游戏之后，我对电子产品也“阳痿”了。

今年趁着国补，我给住处添置了一台雷鸟电视，但发现观看 YouTube 颇为不便，便萌生了入手一台可玩性更高的路由器的想法。一番精挑细选后，我入手了红米 AX6000。到手后，我便迫不及待地刷入了 OpenWrt 固件，结果却事与愿违，网速极不稳定。我又尝试了两三个不同版本的固件，问题依旧。无奈之下，只得刷回官方固件。所幸我的需求在官方固件下也能得到满足，最终我选择了固化 SSH 并安装了 ShellClash。这次折腾路由器的经历，让我找回了些许久违的乐趣，但也不得不承认，曾经的我享受的是折腾本身，而现在，我只想用最简单高效的方式解决问题。

年少时，有的是时间和精力，肆意挥霍，瞎折腾也是一种乐趣。但随着年龄增长，家庭、工作占满了时间，责任与压力纷至沓来，时间变得宝贵，便不再沉溺于无谓的折腾，不自觉地求稳。这或许并非是坏事，关键点如何在“折腾”与“不折腾”之间找到一个平衡点，找到那个让自己最舒适的姿态，而更重要的是，不要让自己丧失折腾的勇气和能力。

生活

iOS 自动化

iOS 自动化（快捷指令）这玩意儿早就有了，但今年，我才真正体会到它实实在在的用处。

下面就分享几个我常用的自动化操作：

上下班打卡

几年前，我就开始尝试用 iOS 快捷指令自动打卡企业微信。最初的方案是结合通勤时间设置闹钟，关闭闹钟时触发。但此方案常因通勤不稳定或需手动确认而失效。后来，我换了思路，改为特定时间内，手机连接/断开公司 Wi-Fi 即自动打开企业微信打卡。改进后方案出奇地稳定，打卡再也没落下过。

取快递提醒

以前下班回家取快递，总要翻找半天短信，甚至打开购物 APP 才能找到取件码，费时费力，让人心烦。后来我做了个自动化：只要短信里有“包裹”之类的关键词，就自动把取件码提取出来，塞进提醒事项里。我还加了个触发条件，每次刷羊城通出站的时候，自动弹出提醒，如此一来，取快递就方便多了。

复制验证码

受“取快递提醒”的启发，我将这一思路应用到了短信验证码的接收上。每当收到包含“验证码”关键词的短信，iOS 快捷指令会自动提取内容，并推送到 macOS 端的 Bark 软件实现自动复制到剪贴板。如此一来，我只需直接粘贴，省去了所有中间步骤，效率倍增。

年度盘点

最喜欢的软件

macOS

我在本站不止一次自诩为 RSS 重度爱好者，痴迷于“万物皆可 RSS”的境界。我甚至幻想过：要是微信朋友圈也能用 RSS 订阅该多好！因此，当集大成者的 RSS 阅读器 Follow 一经推出，我便迫不及待地四处寻求邀请码。最近得知 Follow 已经在推出移动端的 TestFlight 版本，期待明年它能成为我在 iOS 上最喜欢的软件。

iOS

今年，我将用了许久的 Shadowrocket 换成了 Quantumult X，没想到这个决定竟带来了意想不到的惊喜。Quantumult X 不仅拥有强大的去广告能力，更以其极高的可玩性著称。它支持各种自动化脚本，让你可以根据自己的需求定制各种功能，我还自己编写了几个自动签到脚本。综合来看，Quantumult X 绝对是我今年剁手最值的软件，没有之一。

TV

我从小就爱看电影，早年为了满足我对电影的渴求，我折腾了个黑群晖当下载机，全天候下载，最终硬盘也因此“阵亡”。后来，使用阿里云盘存电影，还搭了个 Alist，但为了搞个漂亮的海报墙，还得自己手动刮削，简直麻烦死了。直到后来，朋友给我安利了 Emby 公益服，从此打开新世界的大门！想看的电影基本都有，还都已经刮削好精美的海报墙，再也不用自己瞎折腾了，观影体验蹭蹭往上涨！

最喜欢的电影

原以为《周处除三害》将是我今年的年度最佳，直到年底黄子华和许冠文合作的《破地狱》上映了！说来也巧，香港首映那天我正好就在香港，但愣是给忘了，现在想起来都想抽自己！原以为这部电影无缘大陆银幕，还好 12 月宣布了定档，我赶紧第一时间买了预售票。

这部电影的优秀无需我赘述，票房成绩便是最好的佐证。于我个人，除了黄子华和许冠文这两位我从小就喜欢的演员同台飙戏——尤其黄子华，他是我心中唯一的男神，看到他如今的成就，我由衷地替他开心。更何况，《破地狱》选择了一个华语电影中鲜少触及的题材——直面死亡与殡葬。我相信，每一个经历过亲人离世，并走过整个殡葬流程的人，都会对这部电影感同身受。

最喜欢的电视剧

前段时间，《白夜追凶》第二部上映的消息刷屏了各大平台，但我对这部剧却一无所知，竟从未看过第一部。于是我找出了 2017 年上映的第一部，谁知这一看便入了迷，一口气追完了全剧。然而，备受期待的第二部却槽点满满，仅看一集便让我没了继续追的欲望。

这也难怪，毕竟续集难超前作已成定律，就像最近的《鱿鱼游戏》第二季，评价就褒贬不一。

最喜欢的音乐

今年有一次，在广场上偶然听到一对情侣对唱《偏爱》，这首歌我之前也听过，但那天不知道为什么，特别有感觉。回去后，我便开始单曲循环，怎么听都不腻！

回顾与展望

真正的成长，就是学会与生活和解，在平凡的日子里，活出自己的精彩。2024 年即将过去，新的一年即将到来。愿我们都能在未来的日子里，继续保持热爱，不负自己。也祝愿每一位朋友，新年快乐，万事胜意，好好睡觉，好好生活！

2024，我使用的工具从 A 到 Z

Tue, 17 Dec 2024 00:00:00 GMT

写在前面

今年有一次，同事突然问我，可有什么好工具推荐。我一时竟怔住，不知如何作答。倒也不是没有，平日里确实积累了不少趁手的工具，只是仓促间让我说出来，倒也为难。

只因每种工具有其特定的适用场景，而每个人偏好亦有不同。正所谓：我之蜜糖，彼之砒霜。

事后想想，其实可以写一篇文章，把我用的工具都介绍一下。虽然数量不少，也不一定都适合每个人，但肯定有人能从中找到适合自己的。所以，我决定参考别人的方式，写一篇我自己的《从 A 到 Z》，把我 2024 年日常工作和生活中使用的各种工具，按照字母顺序一一列出来，和大家分享。

以下是一些工具的分类，包括 macOS、iOS、安卓 TV 等系统软件、各类网站、浏览器扩展以及命令行工具和 npm 包。为了方便查阅，我将首先按类型分类，再在各类中按字母顺序排列。

macOS 软件

APTV

吃饭时追电视的好帮手！支持苹果全家桶，虽不自带直播源，但配合自定义源简直绝了。

我个人维护了一套包含卫视频道、港台频道和网络直播的源，如有需要可邮件联系。

Applite

免费开源的 macOS 工具，专为 Homebrew 第三方应用的安装和管理设计，操作更直观，省时省力。

Bob

Bob 是一款强大的翻译和 OCR 工具，通过选择文本并按下快捷键 (Option + D) 即可快速翻译或进行 OCR 识别，配合 PopClip 甚至可以实现无键盘操作。更重要的是，Bob 支持自定义 AI 接口和提示语，实现高度个性化的翻译、润色、解释等功能。以下是我常用的几个提示语示例：

1. 翻译（使用 Pro 用户专属的「智谱翻译官」）

<details> <summary>点我展开提示语</summary>

出处：https://x.com/dotey/status/1727091267870367880

角色设定

你是一位精通 $query.detectToLang、$query.detectFromLang 的专业翻译，尤其擅长将专业学术论文翻译成浅显易懂的科普文章。请你帮我将以下 $query.detectFromLang 段落翻译成 $query.detectToLang，风格与 $query.detectToLang 科普读物相似。

规则：

- 翻译时要准确传达原文的事实和背景。
- 即使上意译也要保留原始段落格式，以及保留术语，例如 FLAC，JPEG 等。保留公司缩写，例如 Microsoft, Amazon, OpenAI 等。
- 人名不翻译
- 同时要保留引用的论文，例如 [20] 这样的引用。
- 对于 Figure 和 Table，翻译的同时保留原有格式，例如：“Figure 1: ”翻译为“图 1: ”，“Table 1: ”翻译为：“表 1: ”。
- 全角括号换成半角括号，并在左括号前面加半角空格，右括号后面加半角空格。
- 输入格式为 Markdown 格式，输出格式也必须保留原始 Markdown 格式
- 在翻译专业术语时，第一次出现时要在括号里面写上英文原文，例如：“生成式 AI (Generative AI)”，之后就能只写中文了。
- 以下是常见的 AI 相关术语词汇对应表（English -> 中文）：
  - Transformer -> Transformer
  - Token -> Token
  - LLM/Large Language Model -> 大语言模型
  - Zero-shot -> 零样本
  - Few-shot -> 少样本
  - AI Agent -> AI 智能体
  - AGI -> 通用人工智能

策略：

分三步进行翻译工作，并打印每步的结果：

1. 根据内容直译，保持原有格式，不要遗漏任何信息
2. 根据第一步直译的结果，指出其中存在的具体问题，要准确描述，不宜笼统的表示，也不需要增加原文不存在的内容或格式，包括不仅限于：

- 不符合中文表达习惯，明确指出不符合的地方
- 语句不通顺，指出位置，不需要给出修改意见，意译时修复
- 晦涩难懂，不易理解，可以尝试给出解释

3. 根据第一步直译的结果和第二步指出的问题，重新进行意译，保证内容的原意的基础上，使其更易于理解，更符合中文的表达习惯，同时保持原有的格式不变

返回格式如下，"{xxx}"表示占位符：

意译

{意译结果}

————

直译

{直译结果}

————

问题
{直译的具体问题列表}

用户指令：

现在请按照上面的要求从第一行开始翻译以下内容为 $query.detectToLang：

$query.text

</details>

润色（使用 bob-plugin-openai-polisher）

<details> <summary>点我展开提示语</summary>

请润色下面的文章，使其更加简洁，同时确保所有原因和理由依然明确。
文章的语气应保持轻松随意，而不会过于正式。

</details>

通俗解释（使用 bob-plugin-openai-translator）

<details> <summary>点我展开提示语</summary>

你是一个严谨的学者，但同时也希望用轻松有趣的方式分享知识。请将以下复杂文本用通俗易懂的口语解释出来。解释时可以适度加入一些幽默元素，例如巧妙的比喻、有趣的类比、轻松的语气等，但幽默的程度要适中，不要喧宾夺主，更不能影响对文本的准确理解。

</details>

Beyond Compare

虽然价格肉疼 ($49.9)，但用过之后真香！Beyond Compare 是一款强大的文件和文件夹对比工具，支持各种文件类型，包括 PDF。对比目录下的文件差异效果极好，还能解决代码冲突。

最近出了 v5，但 v4 已经足够用了，不必升级。

Bitwarden

之前从来不用密码管理器，但入职这家公司后被强制要求，才发现它的好用之处。

我选了 Bitwarden，起初打算自建服务，但官方版本已经完全够用。

如果你还没用过密码管理器，强烈推荐开始用，安全又方便。

Charles

macOS 抓包必备神器，用过的都懂，不用多说。

ClashX Pro

和 Charles 类似的工具，如果不是用这个，应该也会用类似的东西。

Command X

macOS 原生不支持 Command + X 文件剪切，但装了它就可以，补齐功能缺失。

Cursor

VSCode 改造而来的 AI 代码编辑器，初体验还不错，但免费期过后价格略贵。

后来接入 deepseek API 用了一段时间，最近转投 Windsurf，体验更棒。

Dash

查文档利器，配合 Raycast 使用效率爆表。

DevUtils

开发者工具合集，小而全，配合 Raycast 更好用。

Fileball

现代化的多媒体播放器，我主要当 Emby 客户端用，跨设备看 Emby 影视非常方便。

FixTim

macOS 故障救星！Wi-Fi 连不上？iCloud 同步出错？别急着重启，试试它能不能修好。

Follow

刷屏社区的 RSS 阅读器，支持电脑端和网页端，体验极佳。

这里安利一下我的梗图 List：梗图列表，有兴趣可以订阅！

Function Key Pro

Fn 键增强工具，让 F1~F12 支持短按、长按和 Fn + 短按三种操作，功能自定义随心所欲。

比如双手腾不出来时，长按 F11 就能调低音量，非常实用。

Hidden Bar

开源的状态栏图标隐藏工具，让状态栏更简洁。

IINA

国产开源播放器，体验很棒，但我用得不多。

Itsycal

菜单栏日历工具，能直接查看日程安排，操作简单，颜值在线。

kitty

之前一直用 iTerm2 作为主力终端，但今年用着总觉得有点不顺手，于是试着折腾了几款新的终端工具。最后选中了 kitty，简单介绍下我的配置和体验。

快速呼出终端：

上学时，我用 Linux Mint 作为主力系统，特别喜欢一个叫 Tilda 的终端工具，它有个超酷的功能：不管你当前在哪个应用窗口，按下 F11 就能瞬间呼出终端窗口。后来切换到 macOS 后，这个习惯一直保留着，只不过工具换成了 iTerm2，现在是 kitty。

在 kitty 里，我用 Raycast 配合快捷键来呼出终端，按下 Option + F11，窗口立刻出现，而且占满屏幕的上半部分。虽然 kitty 不原生支持快捷键显示窗口，但这个搭配已经非常顺手了。

窗口尺寸配置：

initial_window_width 54c
initial_window_height 10c

快捷键适配：

为了保持之前用 iTerm2 的操作习惯，我也在 kitty 里折腾出了一些相似的快捷键。比如，按下 cmd + d 就能快速分割一个 panel。用起来几乎无缝衔接，效率直接拉满。

map cmd+1 goto_tab 1
map cmd+2 goto_tab 2
map cmd+3 goto_tab 3
map cmd+4 goto_tab 4
map cmd+5 goto_tab 5
map cmd+6 goto_tab 6
map cmd+7 goto_tab 7
map cmd+8 goto_tab 8
map cmd+9 goto_tab 9
map cmd+0 goto_tab 10

map cmd+enter toggle_fullscreen

enabled_layouts splits,stack

map cmd+d launch --cwd=current --location=vsplit
map cmd+shift+d launch --cwd=current --location=hsplit
map cmd+w close_window
map cmd+t new_tab_with_cwd

搜索功能：

kitty 不支持用 cmd + f 快捷键来搜索输出的内容。因此从网上找了两种方法实现搜索功能。

# fzf
map ctrl+f launch --type=overlay --stdin-source=@screen_scrollback /opt/homebrew/bin/fzf --no-sort --no-mouse --exact -i
# https://github.com/trygveaa/kitty-kitten-search
map cmd+f launch --allow-remote-control kitty +kitten kitty/kitty_search/search.py @active-kitty-window-id

KeyboardHolder

一款根据不同应用、不同网站、不同场景自动切换到对应的输入法的辅助工具。

Latest

可以帮你快速检查系统中有哪些软件需要更新。

LICEcap

开源的 GIF 屏幕录制小工具，用它就够了。

LocalSend

免费、开源、跨平台的文件分享工具。

Logseq

近几年，「第二大脑」这个概念非常火爆，简单来说，就是将要记住的信息存储在笔记工具里，把大脑留给思考和创造。

支持反向链接（Backlink）的笔记软件是最适合用作第二大脑的工具，你只需输入关键词，就能轻松回溯相关内容，拓展思维。

Logseq 就是这种类型的优秀代表。虽然它并不是所有人心目中的“最佳选择”，但它高度适配「输入 → 整理 → 回顾」的流程。

提醒：别陷入折腾软件的死循环，选一个顺手的工具，专注输入和输出才是正道！

Marta

macOS 自带的 Finder（访达）一向饱受诟病，功能简单又鸡肋。这时，Marta 就能解救你！它支持多栏操作，非常方便进行文件拷贝等操作。如果你想试试其他选择，QSpace 也是不错的替代方案。

Microsoft Edge Dev

这几年，我的主力浏览器一直是 Microsoft Edge，尤其是 Dev 版本。

尝试过其他浏览器（Arc）后，我还是回到了 Edge，毕竟熟悉的工具才是最顺手的。

Notion

虽然现在我的笔记已经迁移到 Logseq，但 Notion 强大的数据库功能依旧让我无法割舍。

收藏管理：配合浏览器扩展 Save to Notion，轻松将文章和网站收集整理。
数据存储：复杂的信息和资源管理，Notion 的数据库能力仍然无可替代。

OrbStack

如果你还在用 Docker Desktop 或 Colima，那么恭喜你发现了更好的选择：OrbStack！

轻量快速：启动速度快，资源占用少。
操作顺滑：整体体验比 Docker Desktop 流畅许多，绝对让你用过之后后悔没早一点发现它。

Parallels Desktop

macOS 上最好用的虚拟机软件，没有之一。

由于我的电脑只有可怜的 512GB，因此我选择将虚拟的 Windows 11 安装在移动硬盘上。

PicGo

一个图床上传工具。

Poe

这个平台集成了多种 AI 模型，价格相比官方渠道便宜不少。我自己没有订阅，只是偶尔用用每天免费的额度，感觉已经够用了。

RapidAPI

前身是 Paw，当初限免时下载的，现在一直在用。相比 Postman，它用起来顺手多了。

Raycast

相信不用我介绍了，但如果你真心不知道这款软件，那么我强烈推荐你使用。

安装 Raycast 后，你可以轻松告别一堆单独的工具，比如：

1. Alfred（更别提 Raycast 免费！）
2. 剪切板管理工具
3. Snippets 代码片段管理工具
4. 软件卸载工具
5. 窗口管理工具
6. 便签工具

Raycast 自带的 Store 拥有丰富的扩展，你可以根据需要找到最适合自己的工具。比如不少主流软件都提供了对应的 Raycast 插件。

借助 Quicklink 功能，你可以自定义命令，比如输入 v2 回车，直接打开 V2EX 摸鱼，效率拉满。

这里我推荐一些常用的扩展：

- Base64：快速解析/编码文本
- ChatGPT：一键召唤 GPT，随问随答
- Google Search：直接启动 Google 快速搜索
- Kill Process：快速查找并 kill 进程
- Microsoft Edge：搜索收藏夹与历史记录
- Search Commands：搜索并查看 Linux 命令
- Search HTTP Status Codes：查阅 HTTP 状态码的含义
- Search npm Packages：快速查找 npm 包信息
- Transform：文本/代码转换神器，例如 CSS 转 JavaScript Object
- Visual Studio Code：直接用 VSCode 打开项目文件

RIME

RIME（中文名“鼠须管”）是一款开源输入法，堪称「神级输入法」。如果你和我一样，想摆脱互联网公司输入法的捆绑，追求更高自由度的自定义配置，那么 RIME 是绝对值得一试的选择。

推荐配置：

rime-ice：基本开箱即用，功能强大。
词库优化：rime-ice 自带的词库虽然够用，但不如搜狗全面，所以我找了个更强的词库配置。

为什么选择 RIME？

1. 高度自定义：支持任意配置方案，可以根据个人输入习惯深度定制。
2. 纯净无广告：没有后台上传数据的烦恼，输入体验干净纯粹。
3. 多平台支持：macOS（鼠须管）、Windows（小狼毫）、Linux（中州韵）都能用。

Remote for Mac

可以在 iOS 上远程操作 macOS 的软件，有时候用它挺方便。

Scroll Reverser

让鼠标滚动方向变得更习惯，尤其是从 Windows 转到 macOS 的用户。

Skim

轻量级 PDF 阅读器，支持标注和笔记，非常适合看书或做研究。

Slack

团队协作的聊天工具，个人感觉比国内同类软件强太多。

Snipaste

从 Windows 开始就用的截图工具，简单快捷。

SnippetsLab

代码片段管理器，用于记录解决方案和命令行代码，配合 Raycast 非常高效。

Sourcetree

虽然更习惯用命令行管理 Git，但遇到复杂操作时，Sourcetree 简直是救星。

Spotify

用尼区车 42/年的价格听歌，值到飞起。

Tor Browser

你懂的。

算了，可能还有人不太懂。简单来说，就是个“洋葱浏览器”，主要用来访问暗网。但别一听“暗网”就觉得都是些见不得光的东西，事实上，暗网里也有很多正常内容。比如之前 z-lib 网站被 FBI 封了，那段时间，只有通过暗网才能继续访问。所以，你懂了吧？

TinyPNG4Mac

一款用于压缩 PNG 图片的工具。可能你不知道，它还有 macOS 客户端。优点是没有文件上传大小的限制，只要申请一个 API key，就能畅快使用，非常方便。

Tuxera Disk Manager

解决 macOS 不支持 NTFS 格式的问题，可以随意读写 NTFS 硬盘。

Typora

Markdown 编辑器，正式版收费，但用习惯了感觉值得。

Velja

双浏览器策略神器，专为解决个人与工作环境混乱而生。你可以根据 URL、应用或快捷键设置不同的默认浏览器，轻松实现账号和插件的彻底隔离。

浏览器里个人和工作账号分不清楚，一直是个让我头疼的问题，尤其是不同的密码管理器插件在同一浏览器中互相冲突，简直让人崩溃。后来我果断采用了双浏览器策略，分别处理工作和个人的账号与插件。

Velja 正是这类需求的完美解决方案：

1. 匹配特定 URL：比如打开公司内部网站，就自动跳转到工作浏览器。
2. 快捷键支持：用 Fn 键加点击，就能快速选择浏览器。
3. 按应用区分：在 Slack 或邮件客户端中点击链接，也能智能地选择对应浏览器。
4. 浏览器插件：选择另外一个浏览器打开当前网页。

简而言之，所有工作相关的内容都会被引导到指定的浏览器，从此告别账号混乱，工作和个人完美隔离。

Visual Studio Code

无需介绍的代码编辑器。

Windows App

macOS 远程连接 RDP 桌面的工具，远程办公必备。

Zen Browser

今年朋友推荐了 Zen 浏览器，它流畅的运行速度和便捷的工作区功能尤其适合打开工作相关的网站。

因此它很自然地成为了我「双浏览器策略」中的选择之一。

iOS 软件

Alook

一块钱的 iOS 浏览器，却拥有强大的功能！无推送、无新闻、无广告，内置播放器还能悬浮播放网页视频，支持倍速和后台播放。强烈推荐！

Authenticator

2FA 验证码管理器，保护你的账户安全。微软、谷歌、LastPass 等都有类似的 APP，我用的是 LastPass 的，功能都差不多，选择你喜欢的就好。

Bark

让你可以把自定义消息推送到手机上的神器，M 系列 Mac 上也能用，玩起来很有意思。

彩云天气

最强天气预报 APP，当年送终身 VIP，但后来加了个 SSVIP 和 AI 小助手。虽说改版了，但天气数据和推送还是很靠谱。

Cape

用屏幕使用时间隐藏 APP，实用且隐秘。

锤子便签

老罗的经典产品，2024 年依然香，操作流畅，用着舒服。

DAMA

聊天打码必备，一键隐私保护，八爷的独立开发作品，简单又实用。

FIMO

复古滤镜相机，随便一拍就是大片。但如果像我一样没审美，效果可能也就那样。

HTTP Catcher

抓包工具，用来劫持请求、修改响应，研究技术或者调试时很好用。

Shortcuts

iOS 的效率天花板，用来自动化各种操作，解锁后你会发现手机更强了。

谜底时钟

充电时仪式感满满的时钟，设计感超棒，买了终身版没后悔。

nplayer

最强播放器，局域网远程播放、全格式支持，无需转码，无广告，一步到位。

Open Scanner

免费的文档扫描 APP，效果杠杠的，在 X 上被安利后就没换过。

Photo Cleaner

清理大图片、相似照片的利器，清理空间的好帮手。

Photomator

系统相册不够用？换它，替代效果一流，还支持 macOS。

Picsew

长截图神器，效果不错，操作方便。

PiP

让 Youtube 视频后台画中画播放（虽然 Alook 也能实现，但多一个选择总归好）。

Quantumult X

比小火箭省电还强大，今年买的最值的一款 APP，完全改变了我的使用习惯。

Reeder

看 RSS 的丝滑神器，手机端、电脑端都顶用，做 RSS 用户的福音。

什么时辰

查看时辰和放小组件的 APP，传统文化爱好者的心头好。

什么值得买

这个不用我多说了，剁手指南。

Stream

又一个抓包工具，简单粗暴。

Termius

功能全面的 SSH 客户端，远程管理必备。

Traffic Rider

无聊时解压的摩托车游戏，开一把放松心情。

Tubecasts

后台听 Youtube 的神器，支持倍速播放和定时关闭，睡觉前听视频专用。

VLLO

视频剪辑工具，操作简单，轻量用户的好帮手。

伟途亦可思

V2EX 的第三方客户端，摸鱼一绝。

小睡眠

助眠神器，睡觉听点白噪音或者轻音乐，秒入梦乡。

熊猫吃短信

超好用的短信过滤工具，熊猫 1 表现很稳，据说熊猫 2 改成订阅制后褒贬不一，所以我一直留在 1。

安卓 TV 软件

BBLL

第三方 bilibili 客户端，支持弹幕，界面清爽，个人感觉比官方版更适合 TV。

Emby

Emby 客户端的破解版，用来看 emby 服的视频，流畅好用。

Simple Live TV

专注看网络直播，涵盖各大网络平台的直播源，小巧实用。

Smartube

无广告的第三方 YouTube 客户端，体验比官方版还丝滑。

tvbox

必备的看剧神器，开源且可定制，各种魔改版本应有尽有。

推荐版本：takagen99，界面美观，使用舒适。

配置地址：http://www.饭太硬.top/tv/，配置完直接开爽。

天光云影

看直播源的软件，支持自定义源，直播体验优秀，操作方便。

一起看 TV

看剧专用，资源丰富、界面简洁，适合电视上轻松追剧。

网站

以下是一些实用的网站，配合 Raycast 的 quicklink 使用可以大幅提升效率。

aistudio.google.com

Google 的 AI Studio，探索和测试 AI 模型的平台，可以免费用最新的模型。

aktv.top

提供稳定的港澳台直播源。

bilin.ai

一个 AI 生成工具平台，用于图片、文本和代码生成。

chatgpt.com

开了 ChatGPT Plus 后一直在用，生产力提升神器。

copilot.microsoft.com

访问 Microsoft Copilot 的专属网站，体验 AI 助理的强大功能。

cs.github.com

快速从 GitHub 仓库中搜索代码，非常方便。

gemini.google.com

Google 的 AI Gemini 项目入口，专注于生成式 AI 的未来探索。

如果可以用 aistudio.google.com，就不需要这个了。

learning.google.com

Google 的在线学习平台，涵盖多种技术和技能的课程。

notebooklm.google.com

Google 推出的 AI 学习工具，用来整理和学习内容特别好用。

npm.runkit.com

在线运行 npm 包的沙盒环境，用于测试和演示代码。

npmgraph.js.org

用图表方式可视化 npm 包的依赖关系。

npmtrends.com

比较多个 npm 包的下载趋势和受欢迎程度。

perplexity.ai

一款结合搜索引擎和问答功能的 AI 工具。

pkg-graph.info

另一个 npm 包依赖可视化工具，帮助理解包的依赖结构。

promptperfect.jina.ai

AI 提示优化工具，生成和测试最佳的 AI 提示。

phind.com

专注于开发者的搜索引擎，直接返回技术相关的搜索结果。

search.luxirty.com

基于 Google 的搜索引擎，屏蔽内容农场，没有广告和跟踪，搜索体验清爽快速。

search.saveweb.org

搜索互联网存档，找回那些已经被删掉的网页内容。

thinkany.ai

AI 相关工具集合，可以探索不同场景下的 AI 应用。

v0.dev

一个实验性开发工具平台。

x.ai

grok AI 应用，现在面向所有用户免费开放。

浏览器扩展

AutoScroll

让 macOS 上也能用鼠标中键自动滚动网页，对 Windows 用户非常友好。

Bypass Paywalls Clean

绕过各种网站的付费墙，轻松访问隐藏内容。

Console Importer

在浏览器控制台一键 import npm 包，调试效率直线上升。

$i("jquery");

Don’t track me Google

屏蔽 Google 的隐私追踪，保护你的数据安全。

JSON Viewer

最强 JSON 查看器，格式化、折叠、查询一气呵成，开发者必备。

Kimi 浏览器助手

总结文章的好帮手，而且完全免费。

OneTab

一键保存所有标签页，整理工作或学习内容神器。

Save to Notion

一键把网页内容保存到 Notion，信息管理更高效。

SimpleExtManager

快速管理浏览器扩展，随用随开，不浪费资源。

SponsorBlock for YouTube

跳过 YouTube 视频的赞助片段，观看体验直接升级。

Stream Recorder

支持下载 HLS / m3u8 格式的直播视频，非常好用。

Velja

想用另一个浏览器打开当前网页？一键搞定。

Video Speed Controller

随意调节视频播放速度，倍速党福音。

Wayback Machine

快速保存网页到互联网档案馆，还能查看过去的版本。

uBlacklist

屏蔽 Google 搜索结果中的指定网站，专治乱七八糟的内容。

uBlock Origin

高效移除广告和跟踪器，浏览器清爽到飞起。

v2ex plus

优化 V2EX 的使用体验，增加各种实用小功能。

沉浸式翻译

深度翻译工具，强烈建议 Linux 用户配合 DeeplX API key 使用。

猫抓

网页上的媒体嗅探神器，各种音视频资源轻松抓取。

篡改猴

油猴脚本管理工具，扩展浏览器功能的不二之选。

过滤广告為 Youtube™

纯粹为 YouTube 服务的广告屏蔽工具，专注且好用。

隐私獾

屏蔽广告和追踪器，还能让你手动选择是否加载一些网页组件。

命令行工具

我会在这里分享一些我常用的命令行工具和自己写的 alias，希望能提升你的终端使用效率。

ag

更好的 grep。

brs

配合 fzf 实现一键切换分支：

brs() {
 gbr | fzf-tmux | awk '{print $1}' | sed 's|origin/||' | xargs -I {} git switch {}
}

btop

更好的 top。

bat

更好的 cat

bclm

有个软件叫 AlDente，它可以帮你调整电池充电阈值。简单来说，当你的电池电量达到设定的数值后，软件会自动停止充电并开始使用电池供电。这样一来，你就不用手动插拔 MacBook 的充电器了。

这款软件是收费的，而 bclm 则是一个开源的命令行工具，可以达到和 AlDente 一样的效果。

使用它后，我的电池健康度一年才降了 5%！不过自从升级 Sequoia 后 macOS 不给写入 SMC 的权限了，所以 bclm 行不通了，现在使用 bclm_loop 代替。

bkp

快速备份文件

bkp() {
  cp -Rp "$1"{,.bak}
}

c

clear 的别名，更快清除屏幕。

cpf

我们都知道 pbcopy 可以复制输出的内容，比如 cat 1.txt | pbcopy。但有时候我们想要复制文件本身，而不是文件内容。这种情况下，通常需要先运行 open . 命令打开当前目录，然后手动拷贝文件。其实可以用纯命令行的方式来操作：

cpf() {
  osascript \
    -e 'on run args' \
    -e 'set the clipboard to POSIX file (first item of args)' \
    -e end \
    "$(pwd)/$@"
}

这样以后我们通过 cpf 1.txt 就能直接在微信等软件中粘贴并发送这个文件了。

difft

理解语法的 diff 工具，可配合 git 或者 hg 使用，让 diff 更好看。

可查看 git 小节查看使用例子。

edge-tts

顾名思义，一个使用 Microsoft Edge 文本转声音的工具，配合 Raycast script 可实现快速阅读一段文本，强烈推荐 xiaoxiao 人声。

fd

更好的 find。

fonttools

一个字体工具，用于生成字体子集或优化文件大小，从而达到瘦身效果，对于前端来说非常好用。

pyftsubset OPPOSans-H.ttf --text=$(cat 仅需要的文本.txt | rg -e '[\w\d]' -oN --no-filename|sort|uniq|tr -d '\n') --no-hinting

fuck

暴躁老哥的命令行工具，当你输错命令的时候，fuck 一下可帮你纠正。

fs

其实是 yazi 的别名，一个很好用的终端文件管理器。

fzf

如果你喜欢命令行操作，那么一定要了解这个工具！它可以让你对所有输出进行模糊搜索和自定义操作。

分享一下我的默认设置：

# 默认选项
export FZF_DEFAULT_OPTS="--height 100% \
--layout reverse \
--prompt '∷ ' \
--pointer ▶ \
--marker ⇒"

# 这行配置开启 ag 查找隐藏文件 及忽略 .git 文件
export FZF_DEFAULT_COMMAND='ag --hidden --ignore .git --ignore .hg -l -g ""'

fzf 在 tmux 下有个很酷的功能，可以让 tab 补全选项列表通过弹出窗体展示，且窗体会更紧凑：

if [[ -n "$TMUX" ]]; then
  zstyle ':fzf-tab:*' fzf-command ftb-tmux-popup
fi

此外，还可以使用 command ** + tab 键的组合来快速预览根目录（例如在执行 cd ** 时）或列出各个指令介绍（例如在执行 git ** 时）。

_fzf_complete_git() {
  _fzf_complete --bind "enter:become(echo {} | awk '{print \$1}')" -- "$@" < <(
    git --help -a | grep -E '^\s+' | awk '{print $1 "       -- " $2, $3, $4, $5}'
  )
}

_fzf_comprun() {
  local command=$1
  shift

  case "$command" in
    tree)         find . -type d | fzf --preview 'tree -C {} -I node_modules' "$@";;
    cd)         find . -type d | fzf --preview 'tree -C {} -I node_modules' "$@";;
    *)            fzf "$@" ;;
  esac
}

你还可以在这个本文里看到很多我使用 fzf 配合其它工具的例子。

git

应该没人不知道了，但你可能不知道，如果你使用的 zsh，那它提供了一系列的 git 的别名：Oh-My-Zsh Git，这里还有一些我与 fzf、difft 等工具配合使用的例子：

# 更好的 git diff
gd() {
  GIT_EXTERNAL_DIFF=difft git diff
}

# 更好的 git show
gsh() {
  GIT_PAGER_IN_USE=1 GIT_EXTERNAL_DIFF=difft git show "$1" --ext-diff | less
}

ggfzf() { fzf --no-sort --ansi --bind "enter:execute(echo {} | sed 's/\x1b\[[0-9;]*m//g' | cut -d' ' -f2 | xargs -I {} bash -c \"source ~/.bash_profile && gd {}\")"; }

# git 提交列表，按回车可快速查看提交信息
gglg() {
  git log --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit | ggfzf
}

h

history | fzf 的别名。

hg

与 git 差不多的版本控制工具，主要我司内部使用这个工具。

虽然我自己也有一套相关的 alias，但由于这个工具用户不多，分享的意义不大，就先不列出来了。

htop

也是更好的 top。

ii

查看当前系统的一些信息。

ii() {
  echo -e "\n您已登录 ${RED}$HOST"
  echo -e "\n附加信息:$NC "
  uname -a
  echo -e "\n${RED}Users logged on:$NC "
  w -h
  echo -e "\n${RED}Current date :$NC "
  date
  echo -e "\n${RED}Machine stats :$NC "
  uptime
  echo -e "\n${RED}Memory stats :$NC "
  free
  echo -e "\n${RED}Diskspace :$NC "
  df -h
  echo -e "\n${RED}Local IP Address :$NC"
  myip
  echo
}

jq

对 json 文件进行操作、过滤等。

jnv

交互式的 jq。

lsd

更好的 ls。

ns

快速打开一个临时目录，做任何实践性的操作。

ns() {
  newdir=`date +%s`
  fulldir=~/Temp/$newdir
  mkdir -p $fulldir
  cd $fulldir
}

nvm

一开始我用的就是这个老牌的 Node.js 版本管理工具，但后来发现它让终端启动太慢，实在受不了，于是换成了 n。可惜在工作中又要求统一用 nvm，只好又换回去了。对于终端启动慢的问题，可以通过冷启动来解决。现在用下来还是能接受的。

# ~/.zshrc
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion

# install zsh-async if it’s not present
if [[ ! -a ~/.zsh-async ]]; then
  git clone git@github.com:mafredri/zsh-async.git ~/.zsh-async
fi
source ~/.zsh-async/async.zsh

load_nvmrc() {
  local nvmrc_path
  nvmrc_path="$(nvm_find_nvmrc)"

  if [ -n "$nvmrc_path" ]; then
    local nvmrc_node_version
    nvmrc_node_version=$(nvm version "$(cat "${nvmrc_path}")")

    if [ "$nvmrc_node_version" = "N/A" ]; then
      nvm install
    elif [ "$nvmrc_node_version" != "$(nvm version)" ]; then
      nvm use > /dev/null
    fi
  elif [ -n "$(PWD=$OLDPWD nvm_find_nvmrc)" ] && [ "$(nvm version)" != "$(nvm version default)" ]; then
    nvm use default > /dev/null
  fi
}

# async_loader
function async_loader() {
  # nvm
  export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
  [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
  load_nvmrc
}

# init worker
async_start_worker async_load_worker -n
async_register_callback async_load_worker async_loader
async_job async_load_worker sleep 0.1

# 改变目录时自动切换 Node.js 版本
add-zsh-hook chpwd load_nvmrc

mdcat

更好地渲染 markdown 的 cat 命令，支持高亮 markdown 语法、代码块、图片等。

ppwd

快速复制当前路径：alias ppwd=pwd | pbcopy。

projclean

项目依赖关系和构建工件清理工具，支持大部分项目。

对于前端来说，它可以帮你一键删除所有项目中的 node_modules 目录，从而释放硬盘空间。

cargo install projclean

# 谨慎操作！！！
projclean node_modules

r

快速切换到当前仓库的根目录。

r() {
  if is_git; then
    cd "$(git rev-parse --show-toplevel)" || return
  elif is_hg; then
    cd "$(hg root)" || return
  else
    cd ~ || return
  fi
}

rsync

rsync 是 linux 系统下的数据镜像备份工具。使用快速增量备份工具。

s

快速应用 .zshrc 等文件而无需重启终端，source ~/.zshrc。

server

快速打开一个 http 服务器：python3 -m http.server 8181。

shellcheck

顾名思义，检查 shell 脚本用的，类似于 eslint 之于 JavaScript。

tldr

查询某个命令的使用示例。

tree

输出当前树形目录结构。

trash

代替 rm，不会直接删除，而是把文件或目录移动到回收站，让你有后悔药吃，可配合 Raycast 的 Empty Trash 指令快速清空回收站。

upp

一键通过 vim 编写提交信息，并进行推送。

git add -A
temp_file=$(mktemp)
vim +startinsert "$temp_file"
commit_message=$(cat "$temp_file")

if [ -z "$commit_message" ]; then
  echo "Commit message was empty. Aborting."
  rm -f "$temp_file"
  return
fi

echo -n "Commit message:"
echo " $commit_message"

echo -n "Do you want to push? (y/N): "

read confirm

git commit -m "$commit_message"

[ $? -eq 1 ] && exit 1

if [[ "$confirm" =~ ^[Yy]$ ]]; then
  git push
fi

rm -f "$temp_file"

vo

使用 fzf 模糊搜索文件并通过 vim 打开：

vo() {
  selected_file=$(_fzf)
  if [ $? -eq 0 ]; then
    nvim "$selected_file"
  fi
}

以此类推可以实现快速通过其它工具打开。

wx

快速通过微信开发者工具当前项目：

wx() {
  /Applications/wechatwebdevtools.app/Contents/MacOS/cli open --project "$(pwd)/$1"
}

yt-dlp

youtube-dl 已死，这是它的代替方案。

z

我以前一直用 z.lua，直到我发现了 zoxide。我觉得这是一个更好的快速跳转目录工具。

而且它还支持使用 zi 命令列出候选目录，然后你可以自己选择要跳转的目录。

zsh

这几年我一直用 zsh，试过一段时间 fish，但发现不太习惯，而且不兼容我的 bash 脚本，所以还是回到了 zsh。目前我在用 p10k 主题，挺不错的！

插件主要是这些：

plugins=(git mercurial-prompt mercurial zsh-autosuggestions fzf-tab zsh-vi-mode pnpm-shell-completion zsh-history-substring-search zsh-syntax-highlighting)

npm 包

这里列出一些可能你不知道的 npm 包，它们能帮你提升开发效率。

c8

生成代码覆盖率报告的神器，基于 Node.js 原生功能，简单好用。

cli-highlight

让终端输出的代码瞬间“高亮”，看日志的快乐你懂的。

fast-glob

速度飞快的文件匹配工具，性能吊打 glob，但只能通过代码调用。

const fg = require("fast-glob");
const entries = await fg([".editorconfig", "**/index.js"], { dot: true });

glob

经典的文件匹配工具，写脚本必备，还支持直接在命令行里用：

glob 'src/**/*.sh' | xargs shellcheck

jscpd

专治代码“复读机”，用来检测代码重复率，保质保量：

jscpd -p "./**/*.js" -k 15 -l 5

ni / nr

自动匹配项目用的包管理器，ni 安装依赖，nr 快速跑脚本，效率拉满。

nolyfill

专治“历史包袱”的工具，替换掉那些为兼容老 Node.js 而存在的多余 polyfill，立减 node_modules 大小 50MiB 以上。

npm-run-all

并发或串行跑 npm scripts，简单又高效。

npm-run-all --parallel lint:*"

npm-check-updates

批量更新依赖版本，想升就升，谁还手动改 package.json。

ncu -i -t latest --packageFile "generators/**/_package.json"

minimist

Node.js 脚本写多了少不了它，轻松解析命令行参数。

typedoc

用 jsdoc 写 TypeScript 注释，生成文档专用。

pnpm typedoc --options typedoc.json

vue-docgen

需要给 Vue 组件生成组件文档？用它，省时省力不糊涂。

结语

以上就是我 2024 年常用的工具，希望能对你有所帮助。当然，每个人的需求和喜好不同，适合我的不一定适合你。如果你有其他好用的工具推荐，欢迎在评论区分享！你最常用的工具是什么？你有什么提高效率的技巧？一起来讨论吧！

对 RSS 的再思考：被忽视的力量

Sat, 19 Oct 2024 00:00:00 GMT

引言

作为一名多年的 RSS 重度用户，我曾通过 RSS 订阅几乎所有你能想到的内容：技术博客、社区帖子、Twitter（现称为 X）的动态、Telegram 消息、YouTube 更新等。得益于开源项目 RSSHub，我可以轻松地制作和订阅各种源。

我甚至尝试过将整本书的所有章节、某个网站的全部内容制作成 RSS 源，每天推送一篇给自己。这种方式既新颖又有趣。

然而，在 2023 年，我几乎停止了使用 RSS。主要原因是我意识到自己花在信息流上的时间过多，影响了工作和生活的其他重要方面。每天花费数小时浏览信息流，大多只是快速浏览标题，真正深入阅读的内容寥寥无几。停用 RSS 后，我突然发现自己有了大量空闲时间，可以专注于看电影、学习新知识，而不必担心信息的积压。

尽管暂停使用 RSS 可能会错过一些新鲜事，但实际上，那些重要的信息往往会通过其他渠道传递给我，例如微信群和朋友的分享。

到了 2024 年，经过一段时间的反思和自我调整，我重新拾起了阅读 RSS 的习惯，在这过程中对 RSS 有了一些新的看法。

RSS 已死？

“RSS 已死”的论调时有耳闻。持这种观点的人通常会举出以下例子：

首先，像 Google 这样的科技巨头早在十多年前就放弃了对 RSS 的支持，似乎各大公司都在有意无意地边缘化这项技术。国内的微信构建了一个封闭的生态系统，其他以 RSS 为卖点的产品在国内市场也难以立足，甚至面临下架的风险。

即使在国外，情况也不容乐观。Twitter 在被马斯克收购并改名为 X 后，进一步收紧了对 RSS 的限制，甚至对 RSSHub 的实例发动了 DDoS 攻击。

在这样的打压下，RSS 似乎已被时代遗忘。就我身边的情况来看，多年来与我共事的同事中，使用 RSS 的人寥寥无几，甚至有人根本不知道 RSS 为何物。

然而，2024 年初，RSSHub 的作者 DIYgod 联合推出了一款新的 RSS 阅读器——Follow。这款产品的出现，引起了广泛的关注。由于邀请码稀缺，各大论坛充斥着关于 Follow 的抽奖和邀请码交易的帖子。一时间，RSS 似乎又回到了大众的视野。

在独立开发者的圈子里，也有越来越多的人开始讨论开发自己的 RSS 阅读器产品。Follow 的出现，的确让一些原本不了解 RSS 的人开始关注和使用它。这似乎与“RSS 已死”的论调相矛盾，RSS 真的要复兴了吗？

被忽视的力量

那么，Follow 的出现能否让 RSS“死而复生”呢？我对此持谨慎的态度。我的看法与一篇文章中所表达的观点非常相似。

我认为，正是因为国内外的科技巨头对 RSS 缺乏兴趣，他们才没有过多干涉 RSS 的发展。这些公司借鉴了 RSS 的理念，打造了自己的封闭式信息流产品，如微信公众号等，但这并不是真正的 RSS。恰恰是这种“被忽视”，使得 RSS 得以保持其纯粹性和开放性。

相反，对于邮件订阅等渠道，科技巨头们却非常热衷，结果导致用户经常收到大量的营销邮件，甚至需要花费精力去取消订阅。

因此，被主流所忽视，反而成为了 RSS 的护身符。它不受商业利益的驱使，能够为用户提供一个自主选择信息的工具。在信息茧房泛滥的今天，RSS 为少数坚持自主获取信息的人提供了一片净土。

Follow 的出现，虽然在一定程度上提高了 RSS 的关注度，但我认为更重要的是它为 RSS 注入了新的活力，让更多人认识到 RSS 的价值。然而，RSS 的核心魅力在于其开放性和用户自主性，这些特质正是由于缺乏商业巨头的干涉而得以保留。

结语

或许，RSS 并不需要复兴，因为它从未真正消亡。它一直存在于那些追求信息自由和自主选择的人们的工具箱中。被忽视，反而使 RSS 免受商业化的侵蚀，保留了其原本的纯粹。这种在夹缝中生存的状态，或许正是一种另类的胜利。

4Ark

每周轮子之 server-only：一个空包背后的“毒药”

前言

v1 Runtime Check

v2 Poison Pill

还有高手？

1. 作者之谜

2. Tree-shaking 的漏网之鱼

3. npm 包作者应有的觉悟

一文讲透 Etherpad 插件开发

Etherpad 是什么

技术架构

插件怎么做？

行内样式开发流程：UI 触发 → 写入属性 → 渲染样式。

注册 UI 和写入属性 (Client Side)

将属性映射为 CSS Class (Client Side)

内容组件化（自定义标签 DSL）

Marked 扩展构建器

实现 TOC 目录组件

多渠道发布系统 (Send2CMS)

AText 转增强 Markdown

渲染隔离与污染治理

避坑与经验

链接嵌套修复与清洗

Iframe 穿透 (jQuery)

服务端路由：大文件上传限制

多 Mac 设备配置同步方案

前言

为什么不用这些方案

目前方案

核心文件说明

备份流程：macup

恢复流程：macdown

OpenSpec 使用心得

一、引言

二、AI 工具演进阶段

三、现有困境与解决方案

OpenSpec 核心思路

四、角色转变

五、OpenSpec 使用案例

1. 安装 OpenSpec

2. 初始化 OpenSpec

3. 创建提案

4. 反复打磨

5. 实施与归档

六、个人实践心得

uni-app 多端组件属性与样式透传行为一致性实践

现状分析

样式隔离

解决方案

方案一

方案二

页面样式优先级

uni-app 与原生小程序混合开发方案

前言

项目现状分析

uni-app 项目复用原生小程序页面

uni-app 项目集成到原生小程序

我如何自己实现 lint-staged

前言

为什么要自己实现 lint-staged？

实现思路

核心代码

2024 年终总结

前言

工作

学习

电子族谱

电子阳痿

生活

iOS 自动化

上下班打卡

取快递提醒

复制验证码

更多...

年度盘点

最喜欢的软件

macOS

iOS

TV