前言

https://github.com/tiagozip/cap

Cap.js 是一种基于工作量证明 (PoW) 的验证码系统。相较于常见的验证码系统（如 Cloudflare Turnstile ，reCAPTCHA，hCAPTCHA），其特色是可自建，无隐私问题，无打扰，体积小。

我的博客的登录、注册等接口就使用了 Cap.js，你可以来 看看效果。

其他的验证码大概分为两类（当然两者可能混合使用），一类是要求用户解决某些困难问题的，例如数字运算、选自行车、人行道等。另一类则是收集用户浏览器的信息，来判断浏览器是否属于正常用户。

而工作量证明类验证码则与他们不同，可以说目标就不一样。其他的验证码主要是为人机验证，防止自动化程序批量请求，所以需要从中辨别出真人。工作量证明类验证码则主要是为了速率限制，通过提高请求成本，来防止大量请求。

其原理与挖矿类似，即给客户端一个需大量计算、但服务器端可轻松验证的问题，例如：服务端发一个种子 + 配置的挑战，客户端在本地用 SHA-256 不断哈希，找到使哈希以目标前缀开头的 nonce，提交给服务端。而服务器端验证时，只需要验证用户答案是否满足条件即可。具体的交互流程大概是两次请求，即：

1. 客户端向服务器获取问题
2. 服务器给出问题，并将问题存储
3. 客户端计算哈希，将结果发送到服务器
4. 服务器验证答案，将Token发送到客户端，并将Token存储

随后，客户端即可用 Token 进行提交请求，服务器端验证Token是否已存储，若已存储则此次质询通过。根据设置，可以选择删除这个已验证过的Token（一次性），或者保留固定时间（有效时期内不再验证）。

从上述流程不难发现，PoW验证码完全不需要用户操作，它将本来给用户的验证流程交给用户的设备来完成。但 PoW 仍具有局限性，如：

• 无法进行人机验证。完全不验证对方是否为真人，只要问题能解决即可。如果对方使用高性能计算集群来快速解决验证码，则仍可以对接口进行高速率请求
• 问题难度固定，各个设备通过时间存在极大差异。为了限制高性能设备的请求速率，难度不能过低，但难度较高同时也会导致低性能设备需要花费较长时间。（你可以前往 官方BenchMark 来对比不同设备解决问题的时间）

其中，对于无法识别机器请求的问题，我通过 Server Action 已经解决了，后面再写个文章讲讲。

但对于不同用户设备算力存在差异的问题，确实没有什么太好的办法，我的方案是主动在进入页面时就开始计算验证码，让用户把等待的时间用来填表单。但是，对于太老的设备，计算时间可能仍超出用户预期。

关于 Cap.js

Cap.js 则是我用着不错的 PoW，比较的轻量，支持较大程度的自定义。想要将其添加到你现有的项目中，你需要分别创建后端和前端部分：

1. @cap.js/server：负责创建挑战、兑换答案、校验 token
2. @cap.js/widget：负责在浏览器端本地计算挑战

安装：

pnpm add @cap.js/server @cap.js/widget

我这个项目里用的是 Redis 来存挑战和 token，你也可以使用内存（Serverless 下不可用）或者数据库等。整体结构是：

1. 服务端初始化一个 Cap 实例
2. 把 challenge 和 token 的读写逻辑接到存储端
3. 暴露三个操作：createChallenge、verifyChallenge、verifyToken
4. 前端加载 widget，在页面打开时就先开始解题
5. 提交登录、注册、评论这些请求时，把 token 带上
6. 实现业务逻辑的时候，先验证请求中的 token 是否有效

实现

后端

后端需完成三个操作： createChallenge 、verifyChallenge 、verifyToken，分别用于创建验证码问题、验证验证码答案并分发token、验证token。三步操作都需要数据存取操作。例如：

// src/lib/server/captcha.ts
// https://github.com/RavelloH/NeutralPress/blob/main/apps/web/src/lib/server/captcha.ts
import "server-only";

import Cap from "@cap.js/server";

import { generateCacheKey } from "@/lib/server/cache";
import redis, { ensureRedisConnection } from "@/lib/server/redis";

export const cap = new Cap({
  storage: {
    challenges: {
      store: async (token, challengeData) => {
        // 以下为你的存储端写入逻辑
        await ensureRedisConnection();
        const ttl = Math.floor((challengeData.expires - Date.now()) / 1000);
        if (ttl > 0) {
          await redis.setex(
            generateCacheKey("captcha", "challenge", token),
            ttl,
            JSON.stringify(challengeData),
          );
        }
      },
      read: async (token) => {
        // 以下为你的存储端读取逻辑
        await ensureRedisConnection();
        const data = await redis.get(
          generateCacheKey("captcha", "challenge", token),
        );
        if (!data) return null;

        const challengeData = JSON.parse(data);
        if (challengeData.expires <= Date.now()) {
          await redis.del(generateCacheKey("captcha", "challenge", token));
          return null;
        }

        return { challenge: challengeData, expires: challengeData.expires };
      },
      delete: async (token) => {
        // 以下为你的存储端删除逻辑
        await redis.del(generateCacheKey("captcha", "challenge", token));
      },
      deleteExpired: async () => {
        // 以下为你的存储端删除过期项的逻辑
        // 不过我用 Redis 的 ttl 实现的自动清理，这里就不用写了
      },
    },
    tokens: {
      store: async (tokenKey, expires) => {
        // 以下为你的存储端写入逻辑
        await ensureRedisConnection();
        const ttl = Math.floor((expires - Date.now()) / 1000);
        if (ttl > 0) {
          await redis.setex(
            generateCacheKey("captcha", "token", tokenKey),
            ttl,
            expires.toString(),
          );
        }
      },
      get: async (tokenKey) => {
        // 以下为你的存储端读取逻辑
        await ensureRedisConnection();
        const data = await redis.get(
          generateCacheKey("captcha", "token", tokenKey),
        );
        if (!data) return null;

        const expires = parseInt(data, 10);
        if (expires <= Date.now()) {
          await redis.del(generateCacheKey("captcha", "token", tokenKey));
          return null;
        }

        return expires;
      },
      delete: async (tokenKey) => {
        // 以下为你的存储端删除逻辑
        await redis.del(generateCacheKey("captcha", "token", tokenKey));
      },
      deleteExpired: async () => {
        // 以下为你的存储端删除过期项的逻辑
        // 不过我用 Redis 的 ttl 实现的自动清理，这里就不用写了
      },
    },
  },
});

其中，challenges存还没被解出的题，tokens存已经解题成功、可以拿去提交业务请求的令牌。

存储方式随意，可以用内存，或者 Redis，或者数据库，甚至 HTTP 数据库。但在 Serverless 下，内存不可用，所以我用的是 Redis ，这样清理也容易多了，带个 TTL 就行，都不用单独写了。

方法

初始化完 cap 之后，后端需要三个操作方法：

1. createChallenge：生成题目
2. verifyChallenge：验证答案并发 token
3. verifyToken：提交表单时检查 token

// src/actions/captcha.ts
// https://github.com/RavelloH/NeutralPress/blob/main/apps/web/src/actions/captcha.ts
"use server";

import { cap } from "@/lib/server/captcha";

export async function createChallenge() {
  const data = await cap.createChallenge({
    challengeCount: 50,
    challengeSize: 32,
    challengeDifficulty: 5, // 5 似乎耗时有点长，我博客里用的就是5，你可以到 BenchMark 里自己试试
    expiresMs: 600000,
  });

  return {
    success: true,
    data,
  };
}

export async function verifyChallenge({
  token,
  solutions,
}: {
  token: string;
  solutions: number[];
}) {
  const data = await cap.redeemChallenge({ token, solutions });

  return {
    success: true,
    data,
  };
}

// src/lib/server/captcha.ts
// https://github.com/RavelloH/NeutralPress/blob/main/apps/web/src/lib/server/captcha.ts
export async function verifyToken(token: string) {
  try {
    const isValid = await cap.validateToken(token, {
      keepToken: false, // 令牌是否可以重复使用
    });
    return isValid;
  } catch (error) {
    return { success: false };
  }
}

Challenge 参数大多都在 官方BenchMark 页面里面有，你可以自己试试。keepToken: false决定令牌是否可以被重复使用，不过似乎可重复使用的令牌也起不到放置批量调用的作用了。

用 Server Action 替代 API

仅为拓展用途，Server Action 目前用的还不是太广泛，如果你的项目没用到过就不用看这段

官方的通信方式是直接使用 fetch 来通信， 但在 NeutralPress 里，我基本都在用 Server Action，官方有 window.CAP_CUSTOM_FETCH 方法来自定义 fetcher：

// src/hooks/use-captcha.ts
// https://github.com/RavelloH/NeutralPress/blob/main/apps/web/src/hooks/use-captcha.ts
useEffect(() => {
  if (typeof window === "undefined") return;

  window.CAP_CUSTOM_FETCH = async function (url, options) {
    const result =
      url === "/challenge"
        ? await createChallenge()
        : url === "/redeem" &&
            options?.body &&
            typeof options.body === "string"
          ? await verifyChallenge(JSON.parse(options.body))
          : null;

    if (result && "success" in result && result.success && result.data) {
      return new Response(JSON.stringify(result.data));
    }

    return new Response(
      JSON.stringify({ error: "Failed to create challenge" }),
      { status: 500 },
    );
  };

  return () => {
    delete window.CAP_CUSTOM_FETCH;
  };
}, []);

从这套实现可以看出，Cap.js widget 仍然在请求 /challenge 和 /redeem，但真正的网络调用已经被转发给 createChallenge() 和 verifyChallenge() 这两个 Server Action 了。

前端

前端核心逻辑在 useCaptcha 这个 hook 里。它会动态导入 @cap.js/widget，然后创建实例、监听进度、监听成功事件：

// src/hooks/use-captcha.ts
// https://github.com/RavelloH/NeutralPress/blob/main/apps/web/src/hooks/use-captcha.ts
import { useCallback, useEffect, useRef } from "react";

let CapClass: unknown = null;

async function loadCap() {
  if (typeof window !== "undefined" && !CapClass) {
    const widgetModule = await import("@cap.js/widget");
    CapClass = widgetModule.default || widgetModule.Cap;
  }
  return CapClass;
}

export function useCaptcha(callbacks?: {
  onProgress?: (progress: number) => void;
  onSolve?: (token: string) => void;
  onError?: (error: unknown) => void;
}) {
  const capRef = useRef<unknown>(null);

  const initializeCaptcha = useCallback(async () => {
    const CapClass = await loadCap();
    const CapConstructor = CapClass as new () => {
      addEventListener: (
        type: string,
        listener: (event: {
          detail: { progress?: number; token?: string };
        }) => void,
      ) => void;
      solve: () => Promise<{ success: boolean; token: string }>;
      reset: () => void;
    };

    const capInstance = new CapConstructor();
    capRef.current = capInstance;

    capInstance.addEventListener("progress", (event) => {
      callbacks?.onProgress?.(event.detail.progress || 0);
    });

    capInstance.addEventListener("solve", (event) => {
      callbacks?.onSolve?.(event.detail.token || "");
    });
  }, [callbacks]);

  const solve = useCallback(async () => {
    if (!capRef.current) {
      await initializeCaptcha();
    }

    return await (capRef.current as {
      solve: () => Promise<{ success: boolean; token: string }>;
    }).solve();
  }, [initializeCaptcha]);

  return { solve };
}

写成 Hook 之后就可以方便的在其他组件里面调用了：

// src/components/ui/CaptchaButton.tsx
// https://github.com/RavelloH/NeutralPress/blob/main/apps/web/src/components/ui/CaptchaButton.tsx
export function CaptchaButton(props: CaptchaButtonProps) {
  const { broadcast } = useBroadcastSender<object>();

  const { solve, reset } = useCaptcha({
    onSolve: (token) => {
      broadcast({ type: "captcha-solved", token });
    },
    onProgress: (progress) => {
      setInternalLoading(progress);
    },
    onError: (error) => {
      broadcast({ type: "captcha-error", error });
    },
  });

  useEffect(() => {
    solve();
  }, [solve]);

  useBroadcast((message: { type: string }) => {
    if (message?.type === "captcha-reset") {
      reset();
      solve();
    }
  });

  return Button({ ...props, loading });
}

你也可以这样把它集成到各种表单提交方式中。为了优化用户体验，最好一挂载就开始验证码，而不是用户点击提交时才开始算，这样能大幅减少用户被阻塞的时间：

useEffect(() => {
  solve();
}, [solve]);

同时，CaptchaButton 还会把进度状态显示成按钮 loading，并在算完后通过广播把 token 发给表单组件。详情看 NeutralPress/apps/web/src/components/ui/CaptchaButton.tsx at main · RavelloH/NeutralPress 。

在表单里使用 token

有了 CaptchaButton 之后，业务表单接入起来就很简单了。例如注册页里：

const [token, setToken] = useState("");

useBroadcast((message: { type: string; token: string }) => {
  if (message?.type === "captcha-solved") {
    setToken(message.token);
  }
});

const register = async () => {
  if (!token) {
    showMessage("安全验证失败，请刷新页面重试");
    return;
  }

  const result = await registerAction({
    username,
    email,
    password,
    captcha_token: token,
  });
};

前端拿到验证成功后传回的 token 后，将其与业务参数一起提交即可。注意检查验证是否成功：

if (!(await verifyToken(captcha_token)).success)
  return response.unauthorized({
    message: "安全验证失败，请刷新页面重试",
  });

在 NeutralPress 中的应用

NeutralPress 里本来就大量使用 Server Action，登录、注册、邮箱验证、评论、友链申请这些动作，都是提交一个表单 -> 进入 Server Action -> 返回结果，Cap.js 刚好也适合放在这个链路里。

此外，我本来就已经给这些接口做了 limitControl 速率限制，所以现在的防护有三层：

1. Server Action 的调用有难度（无法简单的使用 http 来请求）
2. 纯请求频率限制
3. 每次关键请求都要先付出一段本地计算成本

大概是我想到的不依靠三方防火墙的最有效的办法了。

总结

优点

1. 可自部署，不依赖第三方验证码平台
2. 对隐私友好，不需要把大量浏览器指纹信息交给外部服务
3. 不打扰用户，0 交互
4. 很适合接在 Server Action 前面，做统一的请求闸门
5. 对批量脚本确实能显著增加成本

缺点

1. 不能识别真人，只能提高自动化请求成本
2. 不同设备的计算耗时差异非常大
3. 仍然需要服务端存储 challenge 和 token
4. 高性能设备或分布式算力仍然可以绕过它（大概没人拿这种高性能集群来打吧？）
5. 对特别老的设备来说，体验可能不太好（）
   

但作为开源自部署验证码来说，已经是相当好的选择了，给到夯。

—— 完。

前言

树状评论看起来只是简单的无限层级的评论回复评论，但在实际场景中很少见。能说的上来的，恐怕只有 Reddit 了。

其余的一般可以分为两种：

1. 没有分层的：例如各类论坛系统（Discoures、Discuz、百度贴吧），一般只使用“@xxx: 回复内容”这样的标识来表示回复关系。
2. 分少数几层的：例如哔哩哔哩、知乎、微信公众号，一层主要评论（评论正文的）+一层该评论的回复串，其中该评论的回复串一般是不继续分层的，也使用“@xxx: 回复内容”这样的标识来表示回复关系。

这两种方式都有比较明显的问题，就是找上下文比较的繁琐。部分 App 会考虑内置上下文查找的功能，例如 Discoures 的查看上文/下文、哔哩哔哩的“查看回复”，但无论怎么后天通过功能来弥补，其还是不能直观的看出“那个帖子回复了哪个帖子”，而是需要依赖上文的功能。考虑以下场景：

• A：123
• B：456
• A：回复B：789
• C：回复A：000

问：此时 C 回复的是 A 的 123 呢，还是 789 呢？

我反正是在哔哩哔哩里面碰到过很多次这个问题了，而且哔哩哔哩只能查看评论（下文），上文是找不到的。

当然，上面的问题也有其他解决方法，非常简单粗暴，直接引用整个上文，例如 Github Issue。但这样导致随着评论层级增加，每个评论的长度也增加了，不仅对数据库不友好，对鼠标滚轮也不太友好。

树状评论则能完美的解决这个问题。我去年写了一个论坛系统，就是使用的树状评论，你可以轻松看到一整个评论串：左上是父评论，右下是子评论，同一缩进的上下评论均为同级。

当然其也是存在缺点的，最明显的是由于有缩进，导致其在深度较大的时候，内容被挤到右侧，左侧大量留空；此外评论看不出所有评论的时间关系，只能看到同级评论的时间顺序。前者可以靠自适应间距来解决，后者只能当作特色了。

此外，为了方便阅读，一般来说你也可以加一些花活来作为辅助功能。例如我上面的论坛系统：德国森林精灵与数字路径 | XEO OS ，支持高亮评论、聚焦评论、hover高亮整个层级、折叠/隐藏，这样阅读体验会更好一些。

这个博客系统也使用了类似的方案，不过考虑到评论不会太多，我把聚焦功能去掉了。本文接下来主要介绍博客系统的这款。

如果真的想把它写得比较舒服，通常还要额外解决几个问题：

1. 评论需要有明确的层级关系
2. 父评论后面应该紧跟自己的子评论，而不是简单按时间打散
3. 顶级评论和子评论最好都支持分页或局部展开
4. 前端需要方便判断一条评论是谁的父评论、谁的祖先评论

在这种情况下，如果只给评论表加一个 parentId，虽然也能勉强做出来，但后面在查询、排序和渲染时会比较麻烦。因此，使用深度优先搜索 + 物化路径来优化性能是个不错的方案。

实现

在 NeutralPress 这个项目里，我用的是邻接表 + 物化路径 + DFS 排序键的组合，在评论创建时就把 DFS 顺序编码进数据库字段，后面查询和渲染的性能就很高了。（实际上，prisma 对无限递归查询的支持不太好，大概只能这样才比较实用。）

也就是：

1. parentId 表示这条评论直接回复谁
2. depth 表示当前层级，前端拿来算缩进
3. path 表示从根评论到当前评论的完整祖先链
4. sortKey 表示这条评论在整棵树中的 DFS 顺序
5. replyCount 记录直接子评论数量，方便前端判断是否需要展开回复

评论表结构

项目里评论表的核心字段大概是这样的：

model Comment {
  id        String   @id @default(uuid())
  content   String

  parentId  String?
  parent    Comment?  @relation("CommentReplies", fields: [parentId], references: [id], onDelete: Cascade)
  replies   Comment[] @relation("CommentReplies")

  depth      Int    @default(0)
  path       String @default("") @db.VarChar(2000)
  sortKey    String @default("") @db.VarChar(500)
  replyCount Int    @default(0)

  @@index([parentId])
  @@index([postId, status, sortKey])
  @@index([pageId, status, sortKey])
  @@index([path])
}

这里最关键的其实不是 parentId，而是后面这些辅助字段。只靠 parentId，你只能知道这个评论的上一级评论，却没法高效查询：

1. 这条评论的所有后代是谁（用于展开）
2. 这棵子树应该排在整篇评论流的什么位置（前端排序）
3. 某条评论折叠后，哪些后代应该一起隐藏
4. 某条评论下方是否还有更多没展开的后代

path、depth 和 sortKey 用于标识这些附加字段。

创建评论时补全树信息

在创建评论时，先查询父评论，再计算自己的 depth，最后回填 path 和 sortKey：

let depth = 0;
let path = "";
let parentSortKey = "";

if (parentId) {
  const parentComment = await prisma.comment.findUnique({
    where: { id: parentId },
    select: { depth: true, path: true, sortKey: true },
  });

  depth = parentComment.depth + 1;
  parentSortKey = parentComment.sortKey;
}

const record = await prisma.comment.create({
  data: {
    content,
    parentId: parentId || null,
    depth,
    path: "",
    sortKey: "pending",
    replyCount: 0,
  },
  select: { id: true },
});

path = parentId
  ? `${parentComment.path}/${record.id}`
  : record.id;

const finalSortKey = parentId
  ? `${parentSortKey}.${record.id}`
  : record.id;

await prisma.comment.update({
  where: { id: record.id },
  data: { path, sortKey: finalSortKey },
});

顶级评论的 path 就是自己的 id，例如：

a

如果 a 下面有个子评论 b，那么它的 path 就会变成：

a/b

再往下一层 c：

a/b/c

于是 depth 也就分别是 0、1、2。如果你想找 a 的所有评论串，只需要：

const comment = { path: "a", postId: "test" };

const descendantCount = await prisma.comment.findMany({
  where: {
    postId: comment.postId,
    path: { startsWith: comment.path + "/" },
    deletedAt: null,
  },
});

此外，项目里还会在子评论创建成功后给父评论的 replyCount + 1，用空间换时间，防止还需要额外判断是否存在子评论。

不过，这里的sortKey 段值直接用了评论 id，能保证的是“树顺序稳定”，不是同级严格按发布时间排序。如果你希望同级也严格按时间升序，可以把每一段换成零填充时间戳、Snowflake，或者每个父评论下的自增序号。

后端返回

如果一篇文章真的有几千条评论，一次性查整棵树、递归组装后再返回，会导致数据库传输的数据太多。我这里加了两层优化（现在的评论系统就是这种）：

1. 首屏只分页拿顶级评论
2. 每个顶级评论先预加载少量子评论，更深的按需展开

顶级评论的查询大概是这样的：

const rootWhere: Prisma.CommentWhereInput = {
  postId: target.id,
  deletedAt: null,
  parentId: null,
  ...(cursor ? { sortKey: { gt: cursor } } : {}),
};

const rootComments = await prisma.comment.findMany({
  where: rootWhere,
  orderBy: { sortKey: "asc" },
  take: pageSize + 1,
  select: commentSelect,
});

也就是说，首屏实际上只看主评论，子评论不加入。但如果完全不带子评论，也就看不出树状效果了。所以需要额外做一层预加载：

每个主评论最多先带 5 条一级子评论，每个一级子评论再最多带 5 条二级子评论。

这样首屏一打开就已经有树状结构的感觉，也不会导致每一页加载的评论数太多。

而当用户点击“展开回复”时，则调用 getDirectChildren，只加载某个父评论的直接子评论：

const where: Prisma.CommentWhereInput = {
  postId: target.id,
  deletedAt: null,
  parentId,
  depth: parentDepth + 1,
  ...(cursor ? { sortKey: { gt: cursor } } : {}),
};

const children = await prisma.comment.findMany({
  where,
  orderBy: { sortKey: "asc" },
  take: pageSize + 1,
  select: commentSelect,
});

这里用了两个条件：

1. parentId = 当前评论 id
2. depth = 父层级 + 1

parentId 用来锁定直属评论，depth 用来再保险，避免脏数据把别的层级混进来。

至于“这条评论下面到底还有多少后代没展开”，可以直接利用 path 的前缀匹配来统计：

const descendantCount = await prisma.comment.count({
  where: {
    postId: comment.postId,
    path: { startsWith: comment.path + "/" },
    deletedAt: null,
  },
});

这就是物化路径的好处，想查整棵子树，不用递归或 WITH RECURSIVE，直接前缀匹配即可。

前端渲染

前端这边我没有真的把评论重新组装成嵌套 children 树，而是直接用后端返回的扁平数组，然后按 sortKey 排序、按 depth 缩进、按 path 判断可见性。

一个简化后的写法如下：

"use client";

import { useMemo, useState } from "react";

type CommentItem = {
  id: string;
  parentId: string | null;
  content: string;
  depth: number;
  path: string;
  sortKey: string;
  replyCount: number;
  author: {
    displayName: string;
  };
};

function isHiddenByCollapse(
  comment: CommentItem,
  collapsedIds: Set<string>,
  commentsMap: Map<string, CommentItem>,
) {
  for (const collapsedId of collapsedIds) {
    const collapsed = commentsMap.get(collapsedId);
    if (collapsed && comment.path.startsWith(`${collapsed.path}/`)) {
      return true;
    }
  }
  return false;
}

export default function TreeComments({
  initialComments,
}: {
  initialComments: CommentItem[];
}) {
  const [collapsedIds, setCollapsedIds] = useState<Set<string>>(new Set());

  const comments = useMemo(
    () =>
      [...initialComments].sort((a, b) =>
        a.sortKey.localeCompare(b.sortKey),
      ),
    [initialComments],
  );

  const commentsMap = useMemo(
    () => new Map(comments.map((comment) => [comment.id, comment])),
    [comments],
  );

  const visibleComments = useMemo(() => {
    return comments.filter((comment) => {
      return !isHiddenByCollapse(comment, collapsedIds, commentsMap);
    });
  }, [comments, collapsedIds, commentsMap]);

  const toggleCollapse = (commentId: string) => {
    setCollapsedIds((prev) => {
      const next = new Set(prev);
      if (next.has(commentId)) {
        next.delete(commentId);
      } else {
        next.add(commentId);
      }
      return next;
    });
  };

  return (
    <div>
      {visibleComments.map((comment) => {
        const hasChildren = comment.replyCount > 0;
        const isCollapsed = collapsedIds.has(comment.id);

        return (
          <article
            key={comment.id}
            style={{ paddingLeft: `${comment.depth * 24}px` }}
          >
            <div style={{ display: "flex", gap: 8, alignItems: "center" }}>
              <strong>{comment.author.displayName}</strong>
              {hasChildren ? (
                <button onClick={() => toggleCollapse(comment.id)}>
                  {isCollapsed ? "展开回复" : "折叠回复"}
                </button>
              ) : null}
            </div>
            <p>{comment.content}</p>
          </article>
        );
      })}
    </div>
  );
}

这个思路和项目里的真实实现是一致的，只是把登录、点赞、分页加载、评论预览这些和文章主题无关的东西都砍掉了。你可以在 NeutralPress/apps/web/src/components/client/features/posts/CommentsSection.tsx at main · RavelloH/NeutralPress 看完整的实现。

核心逻辑是：

1. 后端返回扁平列表，但已经按 sortKey 排好了 DFS 顺序
2. 前端直接 map 渲染，不需要再递归建树
3. 缩进靠 depth，折叠靠 path 前缀判断

在实际项目里，我还额外维护了一个 childPaginationMap，用来区分“这条评论是折叠了”还是“这条评论的子评论其实还没加载出来”，这样局部展开和分页加载都更自然。

原理

树状评论排序

假设现在有这样一棵评论树：

A
| B
| | C
| D
E

如果把它们的 sortKey 设计成：

A
A.B
A.B.C
A.D
E

那么只要按字符串升序排序，结果天然就是一次深度优先遍历：

A
A.B
A.B.C
A.D
E

也就是说，数据库的压力非常小，只是在按一个普通字符串字段排序而已；真正让这个顺序看起来像树的，是前端根据 depth 做的缩进。

整套方案的重点并不是 DFS 算法本身，而是把 DFS 的结果提前编码进了 sortKey 里，也就是物化路径。

path 和 sortKey 的区别

这两个字段看起来有点像，但职责其实完全不同：

1. sortKey 负责排序和游标分页
2. path 负责祖先链判断和子树查询
3. depth 负责缩进和直接层级判断

只用 path 也不是完全不行，但会有两个问题：

1. 不好做稳定分页，因为“某条评论之后是谁”这件事本质上还是排序问题
2. 前端做折叠时，容易把“祖先关系判断”和“显示顺序”搅在一起

分成三个字段之后就很清晰了：

1. 一条评论是不是另一条评论的后代：看 path.startsWith(parent.path + "/")
2. 整篇评论流应该怎么排：看 sortKey
3. 该往右缩进多少：看 depth

前端不使用递归来建树而使用扁平数组

做评论树，一般都是把数据组装成：

type TreeComment = Comment & {
  children: TreeComment[];
};

这样当然能 render，我在 XEOOS 里面就是这样做的，但我发现，一旦要做局部展开、只加载直接子评论、根评论无限滚动，递归就会重复太多次，且随着同屏评论的增加而性能下降。

这个项目里前端保留的是扁平数组，

1. 首屏加载 10 条顶级评论
2. 某个父评论展开后，把新拿到的子评论按 sortKey 合并进原数组
3. 渲染时直接遍历一遍
4. 哪些该显示，靠 path 和展开状态判断

这样做有几个非常实际的好处：

1. 增量合并简单，mergeBySortKey 一次搞定
2. 分页简单，根评论和子评论都可以走同一套 cursor 思路
3. 折叠简单，只要判断当前评论是不是某个折叠节点的后代
4. 高亮祖先路径也简单，可以用comment.path.split("/") 直接拿祖先链

所以从渲染树的角度看它像树；但从状态管理的角度看，它其实一直是个有顺序的扁平列表。

总结

优点：

1. 父评论后面天然跟着自己的子评论，渲染方便
2. 折叠、展开、高亮祖先、局部加载都很好做
3. 不需要数据库递归查询，查询性能高
4. 前后端都只是在处理排序好的列表，复杂度低

缺点：

1. path 和 sortKey 都是冗余字段，浪费一点空间
2. 如果要移动一整棵子树，后代所有节点的 path / sortKey 需要一起改
3. 当前实现若直接用 UUID 片段做 sortKey，同级顺序不是严格时间顺序
4. 深度特别大时，移动端缩进空间还是会被吃掉，但这个属于树状评论的通病。

不过对于博客评论这种读多写少、完全不移动树的场景这套方案是足够了。实际上，项目的媒体管理系统也是用的这套类似的方案来实现虚拟文件夹，这里就用到了移动树，有时间我再写一写。

—— 完。

前言

NeutralPress 自带图片优化，使用 Next.js 内置的图片优化来自带裁剪并压缩图片，在每个设备上都能给出适配其实际显示大小的图片。

这的确在一定程度上，让图片体积更小、加载更快，然而，图片优化极其消耗性能，所以各家给的限额都很少。强如 Vercel 和 Cloudflare，也都仅仅只提供每月 5000 次转换。如果短期之内上传大量图片，则很容易导致你的 Billing 不太好看。

不过，Cloudinary 则提供了很大方的额度：免费版（Free Plan）每月提供 25 个积分，每个积分可以用来提供 1000 次转换，或者 1 GB 存储，或者 1 GB 带宽。

其中消耗最快的一般是带宽，所以这里我们引入 Cloudflare 来对每个请求尽可能的缓存。理想情况，除了第一次请求、后续请求完全由 Cloudflare CDN 来处理。此外，Cloudflare 也能顺便用来解决 Cloudinary 默认域名访问异常、容易被恶意请求刷优化次数的问题。

NeutralPress 在上传图片的时候会将其转为 avif 并压缩，在我个人这里的话，截图一般能压到 30 KB 左右，普通图片大概 300 KB。按平均一张照片 200 KB 算的话，单张照片的成本是：

• 转换费： 1 次转换 = 0.001 积分（1/1000）。
• 带宽费： 200KB ≈ 0.00019GB = 0.00019 积分（传给 Cloudflare）。
• 存储费： 200KB ≈ 0.00019GB = 0.00019 积分（存在 Cloudinary）。
• 单张总计： 0.00138 积分

也就是说，理论上每月可以处理$\frac{25 \text{ 积分}}{0.00138 \text{ 积分/张}} \approx 18,115$张图片。虽然 Next.js 的图片优化一般会生成很多个不同尺寸的图片，但在这个额度下，应该也没有任何额度焦虑了。

原理

下面以 NeutralPress 举例，实际上所有使用 next/image 组件的都可以用。或者，如果不是 Next.js ，自己写一个根据当前图片实际显示宽度获取对应尺寸的照片的 Image 组件也可以。

'use client'
 
import Image from 'next/image'
 
const imageLoader = ({ src, width, quality }) => {
  return `https://example.com/${src}?w=${width}&q=${quality || 75}`
}
 
export default function Page() {
  return (
    <Image
      loader={imageLoader}
      src="me.png"
      alt="Picture of the author"
      width={500}
      height={500}
    />
  )
}

默认情况下，你可以认为 Next.js 内置的 Loader 就是 /_next/image?url={url}&w={width}&q={quality}，因此只需要修改它，改成先请求 Cloudflare Worker => Worker 再请求 Cloudinary => Cloudinary 从你的图片源中获取图片并优化 即可。

其中，Worker 负责转发请求的同时，还需要验证请求参数，防止有意外的断点大小，造成额外的 Cloudinary 调用。

步骤

首先需要一个 Cloudinary 账号，然后点击左下角 Settings - Security，在Allowed fetch domains 中添加你的域名。

然后，前往 dash.cloudflare.com ，新建一个 Worker，选择”从 Hello World“开始即可。

然后点击编辑代码：

把 hello word 修改成下列内容：

export default {
  async fetch(request, env, ctx) {
    const urlObj = new URL(request.url);
    const params = urlObj.searchParams;

    // ==========================================
    // 1. 配置区域 (Configuration)
    // ==========================================

    // Cloudinary Cloud Name
    const cloudName = 'your_cloud_id';
    // 当输入是相对路径时，拼接的域名
    const defaultOrigin = 'https://ravelloh.com';
    // 可选尺寸参数
    const allowedWidths = new Set([32, 48, 64, 96, 128, 256, 384, 640, 750, 828, 1080, 1200, 1920, 2560]);
    // 可选质量参数，（75的时候，交由 Cloudinary 自动处理）
    const allowedQualities = new Set([75]);
    // 允许代理的域名
    const allowedDomains = new Set(['ravelloh.com']);
    // 防盗链白名单（留空则关闭防盗链）
    const allowedReferers = new Set([
      'ravelloh.com',
      'localhost'
    ]);
    // 是否允许空 Referer (建议 true，否则无法直接在浏览器/部分App打开图片)
    const allowEmptyReferer = true;

    // ==========================================
    // 2. 基础请求处理 (CORS & Methods)
    // ==========================================

    // 处理 OPTIONS 预检请求
    if (request.method === 'OPTIONS') {
      return new Response(null, {
        status: 204,
        headers: {
          'Access-Control-Allow-Origin': '*',
          'Access-Control-Allow-Methods': 'GET,HEAD,OPTIONS',
          'Access-Control-Allow-Headers': 'Content-Type',
          'Access-Control-Max-Age': '86400',
        }
      });
    }

    // 只允许 GET 和 HEAD
    if (request.method !== 'GET' && request.method !== 'HEAD') {
      return new Response('Method Not Allowed', { status: 405 });
    }

    // ==========================================
    // 3. 防盗链检查 (Hotlink Protection)
    // ==========================================
    const referer = request.headers.get('Referer');
    if (referer) {
      try {
        const refererUrl = new URL(referer);
        const hostname = refererUrl.hostname;

        // 检查 Referer 是否在白名单中 (允许子域名)
        const isAllowed = Array.from(allowedReferers).some(allowed =>
          hostname === allowed || hostname.endsWith(`.${allowed}`)
        );

        if (!isAllowed) {
          // 放行搜索引擎爬虫
          const ua = (request.headers.get('User-Agent') || '').toLowerCase();
          const isBot = ua.includes('googlebot') || ua.includes('bingbot') || ua.includes('twitterbot');

          if (!isBot) {
            return new Response('Hotlinking Not Allowed', { status: 403 });
          }
        }
      } catch (e) {
        // Referer 格式异常，视为不通过
        console.log(`[Block] Invalid Referer: ${referer}`);
        return new Response('Invalid Referer', { status: 403 });
      }
    } else {
      // Referer 为空时的处理
      if (!allowEmptyReferer) {
        return new Response('Hotlinking Not Allowed (Empty Referer)', { status: 403 });
      }
    }

    // ==========================================
    // 4. 健康检查 & 参数验证
    // ==========================================

    let imageUrl = params.get('url');
    // 如果没有 url 参数，返回服务状态 JSON
    if (!imageUrl) {
      return new Response(JSON.stringify({
        status: "active",
        service: "Image Optimization Proxy",
        region: request.cf?.colo || "unknown",
        time: new Date().toISOString()
      }, null, 2), {
        status: 200,
        headers: {
          'Content-Type': 'application/json; charset=utf-8',
          'Access-Control-Allow-Origin': '*',
          'Cache-Control': 'no-store'
        }
      });
    }

    // URL 格式化与校验
    try {
      if (!imageUrl.startsWith('http')) {
        if (imageUrl.startsWith('//')) {
          imageUrl = 'https:' + imageUrl;
        } else {
          imageUrl = new URL(imageUrl, defaultOrigin).toString();
        }
      }
      const targetUrlObj = new URL(imageUrl);
      // 限制只能代理白名单域名的图片
      if (!allowedDomains.has(targetUrlObj.hostname)) {
        return new Response('Forbidden: Domain not allowed', { status: 403 });
      }
    } catch (e) {
      return new Response('Invalid URL', { status: 400 });
    }

    const width = parseInt(params.get('w'), 10);
    const quality = parseInt(params.get('q'), 10);

    if (!width || !quality) {
      return new Response('Missing required parameters: w, q', { status: 400 });
    }
    if (!allowedWidths.has(width)) return new Response('Invalid width.', { status: 400 });
    if (!allowedQualities.has(quality)) return new Response('Invalid quality.', { status: 400 });

    // ==========================================
    // 5. 格式归一化 (Format Normalization)
    // ==========================================

    // 将复杂的 Accept 头坍缩为简单的 key，提高缓存命中率
    const acceptHeader = request.headers.get('Accept') || '';
    let format = 'auto';
    if (acceptHeader.includes('image/avif')) {
      format = 'avif';
    } else if (acceptHeader.includes('image/webp')) {
      format = 'webp';
    }
    // 其他情况 format = 'auto' (通常回退到 jpeg/png)

    // ==========================================
    // 6. 缓存键构建 (Cache Key Construction)
    // ==========================================

    // 使用固定的 URL 结构作为 Cache Key，确保参数顺序一致
    const cacheKeyUrl = new URL('http://cache-key');
    cacheKeyUrl.searchParams.set('url', imageUrl);
    cacheKeyUrl.searchParams.set('w', width.toString());
    cacheKeyUrl.searchParams.set('q', quality.toString());
    cacheKeyUrl.searchParams.set('f', format);

    // 强制使用 GET 方法的 Request 对象作为 Key
    const cacheKeyReq = new Request(cacheKeyUrl.toString(), { method: 'GET' });
    const cache = caches.default;

    // ==========================================
    // 7. 缓存查询与回源逻辑
    // ==========================================

    let response = await cache.match(cacheKeyReq);

    if (!response) {
      // --- Cache Miss: 回源 Cloudinary ---
      console.log(`[Cache Miss] ${imageUrl}`);

      const qualityParam = (quality === 75) ? 'q_auto' : `q_${quality}`;
      const encodedImageUrl = encodeURIComponent(imageUrl);
      const cloudinaryUrl =
        `https://res.cloudinary.com/${cloudName}/image/fetch/` +
        `f_${format},c_limit,w_${width},${qualityParam}/` +
        `${encodedImageUrl}`;

      try {
        const originResponse = await fetch(cloudinaryUrl, {
          headers: {
            'User-Agent': 'Cloudflare Worker Image Proxy'
          }
        });

        if (!originResponse.ok) {
          // 返回源站错误信息，方便调试
          return new Response(`Upstream Error: ${originResponse.status}`, { status: 502 });
        }

        // --- 构建优化的响应头 ---
        const newHeaders = new Headers(originResponse.headers);

        // 允许跨域
        newHeaders.set('Access-Control-Allow-Origin', '*');

        // 强缓存配置 (1年 + immutable)
        newHeaders.set('Cache-Control', 'public, max-age=31536000, s-maxage=31536000, immutable');
        newHeaders.delete('CDN-Cache-Control');
        newHeaders.delete('Cloudflare-CDN-Cache-Control');
        newHeaders.delete('Pragma'); 

        // 标记实际返回的格式
        newHeaders.set('X-Image-Format', format);

        // 删除 Vary 头，防止缓存碎片化
        newHeaders.delete('Vary');

        // 清理不必要的头
        newHeaders.delete('Content-Disposition');
        newHeaders.delete('Set-Cookie');

        // --- Stream 处理 ---
        // 1. 创建返回给用户的 Response
        response = new Response(originResponse.body, {
          status: originResponse.status,
          statusText: originResponse.statusText,
          headers: newHeaders
        });

        // 2. 克隆 Response 用于写入缓存
        const responseToCache = response.clone();

        // 3. 异步写入缓存
        ctx.waitUntil(cache.put(cacheKeyReq, responseToCache));

      } catch (error) {
        return new Response('Image Fetch Error', { status: 502 });
      }
    } else {
      // --- Cache Hit ---
      console.log(`[Cache Hit] ${imageUrl}`);
      const newHeaders = new Headers(response.headers);
      newHeaders.set('X-Cache-Status', 'HIT');

      // 重建 Response 以便修改 headers
      response = new Response(response.body, {
        status: response.status,
        statusText: response.statusText,
        headers: newHeaders
      });
    }

    // ==========================================
    // 8. HEAD 请求处理
    // ==========================================
    // 如果是 HEAD 请求，只返回 Headers，不返回 Body
    if (request.method === 'HEAD') {
      return new Response(null, {
        status: response.status,
        statusText: response.statusText,
        headers: response.headers
      });
    }

    return response;
  },
};

这个是我写的比较完善的一版，目前的图片分发就是用的这个。这能做到：

• 防盗链
• 限制参数（w/q），防止恶意构建的请求
• 限制代理 url 模式，防止被代理其他域名
• 内容协商（自动判断应该发放 avif / webp / 其他）
• 边缘缓存，使用 Cloudflare Cache 来进行缓存
• 缓存键清理，即便 Vary 头不同、参数顺序不同，仍能使用同一份缓存

这还能绕过两个付费功能：Cloudflare 自带的缓存清理是收费的；Cloudinary 的免费版的 f_auto 并不会自动返回 avif 格式的图片。因此，这里在 Worker 里我手动处理了。

配置

Cloudinary Cloud Name

就是主页左上角的这个

defaultOrigin

有时你传入的url网址是相对路径的，比如/p/xxxxxxxxxxxx，这个字段在传入相对路径时，将其拼接为完整url。填你的站点地址即可。

allowedWidths

w参数允许的值，一般是 next.config.js里面 image 的 imageSizes+ deviceSizes。

allowedQualities

next/image 里是默认75，此时会让 Cloudinary 自行决定。

allowedDomains

url 如果是个完整路径，其允许的域名列表。

allowedReferers

允许的 referers 来源，用于防盗链

allowEmptyReferer

是否允许空 referers 请求，这不仅会拦截从其他网站发来的请求，还会拦截直接打开和下载等操作。不建议开启，因为实际没什么防护效果，referer 改一下就行。

效果

不出意外的话，你的 Bandwidth 和 Storage 应该差别不大。这就说明 Cloudflare Worker 正确的起到了缓存的作用。

前言

可能是目前最详细的中文 Meteor 文档。

什么是 Meteor ?

Meteor，中文译名彗星端，是一款 Minecraft 外挂辅助模组。其运行在客户端，修改部分客户端行为，让你不管是看起来还是用起来都像是“开了"一样。尽管其不应该被运行在任何服务器中，其对单人生存等场景仍有着十分炸裂的辅助提升效果。但因其不支持中文，这里我专门写篇文章来详细说明下 Meteor 如何使用。

不过我在此再次重申，其不应该被运行在任何服务器中。

叠甲：我不玩PVP，没在除自己以外的任何服务器上使用此工具，这篇文章主要是因为某生电服服主允许并提倡玩家使用此类工具，所以给群友写个教程。

以下内容请善用右侧目录功能来快速查询。

安装

Meteor只能运行在Fabric上。

你可以在官网(Meteor Client)下载到 Meteor 的最新版本。但官网也只会提供最新版本，这意味着你只能在 Minecraftr 的最新正式版上使用此模组。

由于此项目无官方汉化支持，所以你也可以直接下载汉化包，不过汉化包只支持1.20以上的几个版本，详见章节#汉化。

要想将其连接至旧版本的世界，有两个办法：

1. 安装最新版本的 Minecraft 与 Meteor，并同时安装 ViaFabricPlus。

• ViaFabricPlus 是 Fabric 平台上 ViaVersion 的更深层次实现，简单来说它可以让你的客户端加入几乎所有版本的 Minecraft 服务器，不需要服务器做什么。下载地址如下。
• ViaFabricPlus - Minecraft Mod
• ViaFabricPlus - Minecraft Mods - CurseForge
• Releases · ViaVersion/ViaFabricPlus

2. 安装 Minecraft 与对应版本的 Meteor。

• 值得注意的是，这个方法并不被官方推荐，因为这可能导致你使用的旧版 Meteor 有当时未修复的漏洞，或者缺失某些新功能。因此，官方并没有提供对应旧版本的 Meteor jar 包。因此，此方法只能使用第三方提供的旧版本 Meteor 备份或者手动从Github上构建，而前者有可能存在jar包被修改的风险。
• 使用第三方 Meteor 备份:
  • ManInMyVan/meteor-archive: A Meteor Client archive.
• 从Github手动编译:
  • 需要安装 Git 。如果你不知道 Git 是什么，请不要使用这个方法，直接使用上面的第三方备份。
  • cmd 运行以下命令:

git clone https://github.com/MeteorDevelopment/meteor-client
cd meteor-client
git checkout v0.5.9 # 此处v0.5.9改成你想要的版本，Meteor与Minecraft的版本对应关系也可以从上面的第三方备份中看到
gradlew build

将你得到的 Meteor Jar 包放入 mods 文件夹中即可，注意需要安装 Fabric 。

如果你正在以方法2使用旧版本的 Meteor ，那么进入世界的时候大概会弹出弹框提示你更新，无视即可。

汉化

由于此项目没有官方支持的中文，所以汉化也需要找第三方。我找到的不错的一个项目是dingzhen-vape/MeteorCN: Meteor的汉化捏，不过其仅支持了1.20.2以上的少数几个版本。

汉化的方式是直接下载其提供的第三方Jar包，不过注意：经过修改的第三方包存在安全风险。

使用

进入游戏，按下右Shift键，即可看到 Meteor 的菜单。

注意，汉化版的菜单和原版的顺序不一样。

菜单分为两部分，最上面的顶栏和下面的功能区。你可以从上面的顶栏来选择功能区显示什么。
顶栏包括 ModuIes Config GUI HUD Friends Macros Profiles 七个区域，下面先说一下设置相关内容：

Config

其中，建议关了自定义字体，这样就能正常显示中文了。（不关的话，方块/生物的文字都不显示）

GUI

控制屏幕上显示的内容的大小/颜色等，调整缩放来设置整个菜单的大小。

HUD

在屏幕上显示以下信息：

需要勾选下方的Active。

Friends

填写玩家名，之后就不会攻击该玩家了。

Macros

消息宏。比如，下方的设置可以让你在按下H键的时候就公屏说"Help!"

Profiles

将当前所有的设置保存成一个档案，可以根据情况随时切其他的档案。

Modules

Modules 中包含了 Meteor 的核心功能，从上到下都说一遍：

Combat(战斗类)

Anchor Aura

• 自动在敌人附近放置并引爆重生锚。
• 在下界 PvP 中常用于快速造成范围伤害。

Anti Anvil

• 反铁砧，防止其他玩家拿铁砧砸你

Anti Bed

• 反床，在周围放置线，防止其他玩家在地狱/末地用床炸你

Arrow Dodge

• 自动躲射来的箭，也可以改成全部投射物。
• 建议一定要开忽略自己，不然自己射箭的时候也会往周围闪。

Auto Anvil

• 自动在你头上放置一个铁砧，防止其他玩家进入你的洞

Auto Armor

• 自动穿戴最佳防具。

Auto City

• 自动挖掉敌人身边的黑曜石方块，为放置水晶创造空间。
• 在 Crystal PvP 中常用于破坏敌人的 Surround 防御。

Auto Exp

• 自动使用经验瓶修复装备或提升等级。
• 在装备耐久降低时持续向脚下扔经验瓶。

Auto Log

• 在生命值过低或检测到致命威胁时自动退出游戏。
• 用于避免被秒杀或装备掉落。

Auto Totem

• 自动将不死图腾切换到副手。
• 在生命值过低或受到高伤害威胁时触发切换。

Auto Trap

• 自动在敌人周围放置方块将其困住。
• 在近战中常与水晶攻击结合，防止敌人逃跑。

Auto Weapon

• 自动切换到最适合的武器。

Auto Web

• 自动在敌人位置放置蛛网以限制行动。
• 在近战中可减缓敌人移动速度。

Bed Aura

• 自动在敌人附近放置并引爆床。
• 在下界和末地 PvP 中利用床爆炸造成高伤害。

Bow Aimbot

• 自动瞄准敌人进行弓箭射击。
• 可自动计算箭矢下坠和飞行时间。

Bow Spam

• 快速、连续地发射弓箭。
• 自动重复拉弓与松弦动作，实现持续输出。

Burrow

• 在脚下瞬间放置一个方块（通常是黑曜石、铁砧），把自己埋进去。
• 用于在激烈战斗中快速防御，防止被水晶或其他攻击秒杀。

Criticals

• 在 Minecraft 里，玩家跳跃攻击会造成暴击（多 50% 伤害）。
• 这个功能会模拟跳跃或直接修改数据包，让你每次攻击都触发暴击，即便你实际上没有跳。

Crystal Aura

• 自动在敌人附近放置末地水晶并立即引爆。
• 在水晶 PvP 中，这是最核心的秒杀手段，可以设置计算最佳放置位置和时机，让水晶爆炸最大化伤害。

Hitboxes

• 增大其他玩家（或实体）的碰撞检测范围（碰撞箱），使你的攻击更容易命中。

HoleFiller

• 自动填充附近的 1x1 洞（通常是黑曜石、石头），防止敌人躲进去进行防御或水晶反击。
• 主要用于压制 Crystal PvP 中的“洞内战术”。

KillAuro

• 自动攻击附近敌人（可结合范围、优先级、背后攻击等逻辑）。

Offhand

• 自动切换副手物品。

Quiver

• 给自己射药水箭。

Self Anvil

• 在自己头顶快速放置铁砧，让铁砧砸下来对自己造成击退或伤害。
• 我也不知道有什么用。

SelfTrap

• 自动在自己脚边放置方块，把自己封在方块中防御敌人攻击（类似 Burrow，但通常是用方块把头部封起来）。

SelfWeb

• 在自己位置放置蛛网，让自己无法移动，从而减少爆炸击退（Crystal PvP 中可以防止被炸飞）、或延缓掉落。

Surround

• 在自己脚周围一圈快速放置方块（通常是黑曜石），形成 1x1 的防御墙，防止敌人贴近放水晶。
• 在水晶战开局阶段非常常见。

Player(玩家类)

AirPlace

• 在空中放置方块。
• 用于在没有支撑方块的情况下快速搭建或防御。

AntiAfk

• 防止玩家被服务器判定为挂机。
• 自动执行小幅移动或随机动作以保持活跃状态。

Anti Hunger

• 减缓或阻止饥饿值下降。
• 通过限制奔跑或跳跃数据包来减少饥饿消耗。

Auto Clicker

• 自动进行鼠标点击操作。
• 可用于快速攻击、建造或破坏方块。

Auto Eat

• 在饥饿值过低时自动进食。
• 自动选择最佳食物并进行食用动作。

Auto Fish

• 自动进行钓鱼操作。
• 检测到鱼上钩时立即收杆并抛竿。

Auto Gap

• 自动食用金苹果。
• 在生命值或吸收效果低于设定值时触发。

Auto Mend

• 自动使用经验瓶修复装备。
• 检测到装备耐久度不足时持续扔经验瓶。

Auto Replenish

• 自动补充热键栏物品。
• 当快捷栏物品耗尽时从背包补充。

AutoRespawn

• 玩家死亡后自动立即重生。
• 跳过手动点击重生按钮的过程。

Auto Tool

• 自动切换到当前操作所需的最佳工具。
• 在挖掘不同方块时自动选择镐、铲、斧等。

Break Delay

• 调整方块破坏间隔。
• 可减少或消除破坏冷却时间。

Chest Swap

• 自动切换鞘翅和胸甲

Exp Thrower

• 自动向地面丢掷经验瓶。
• 用于快速修复装备或升级。

Fake Player

• 生成一个假玩家实体。
• 可用于测试攻击、防御或假装在线。

Fast Use

• 缩短使用物品的冷却时间。
• 快速放置方块、吃食物或使用药水。

Ghost Hand

• 在没有视线的情况下与方块交互。
• 可穿过方块打开箱子。

Instant Rebreak

• 方块被中断破坏后立即再次开始破坏。
• 在敌人妨碍挖掘时保持高效率。

Liguid Interact

• 与液体方块进行交互。
• 在水或岩浆上放置方块或使用物品。

Middle Click Extra

• 中键点击触发额外功能。
• 可绑定为快速放置方块、攻击或切换物品。

Multitask

• 允许同时进行多个操作。
• 在挖掘方块的同时吃东西或使用其他物品。

Name Protect

• 隐藏或替换玩家昵称。
• 在录屏或直播时保护隐私。

No Interact

• 阻止与特定方块或实体交互。
• 防止误点击箱子、工作台等。

No Mining Trace

• 防止方块破坏痕迹被发现。
• 绕过某些反作弊对挖掘路径的检测。

No Rotate Portals

• 禁止通过传送门时视角被强制旋转。
• 保持原有视角方向不变。

Potion Saver

• 延长药水效果持续时间。
• 在效果接近结束时才使用新药水。

PotionSpoof

• 伪装或修改药水效果。
• 让服务器认为玩家拥有不同的药水状态。

Reach

• 增加手长。

Rotation

• 锁定角度。

SpeedMine

• 提高方块破坏速度。
• 缩短破坏时间，实现快速挖掘。

Movement(移动类)

Air Jump

• 在空中进行跳跃。
• 用于多段跳跃或在空中保持高度。

Anchor

• 将玩家位置固定在特定坐标。
• 防止在边缘或高处被击退掉落。

Anti Void

• 防止掉入虚空。
• 检测到下方为空时自动传送回安全位置或进行反向移动。

Auto Jump

• 自动跳跃。
• 在行走到方块边缘或前进时自动进行跳跃。

Auto Walk

• 自动持续向前行走。
• 可配合挂机或长距离移动使用。

Auto Wasp

• 自动躲避攻击或投射物。
• 在检测到威胁时快速改变位置。

Blink

• 暂存移动数据包并一次性发送。
• 在客户端移动但服务器位置保持不变，释放时瞬移到新位置。

Boat Fly

• 使用船在空中飞行。
• 控制船只脱离地面或水面进行移动。

Click Tp

• 通过点击位置实现瞬间传送。
• 在点击方块或地面时将玩家移动到该位置。

Elytra Boost

• 为鞘翅飞行提供额外加速。
• 使用烟花或其他方式提升飞行速度。

Elytra Fly

• 使用鞘翅在空中持续飞行。
• 控制飞行方向与速度，不依赖重力下落。

Entity Control

• 控制被骑乘的实体方向与移动。
• 用于操控猪、马或其他坐骑。

Entity Speed

• 提高骑乘实体的移动速度。
• 加速马、船或矿车等的行进速度。

Fast Climb

• 提升攀爬梯子或藤蔓的速度。
• 缩短上升所需时间。

Flight

• 在生存模式下自由飞行。
• 不受重力限制，可随意升降和移动。

Gui Move

• 在打开界面时允许移动。
• 打开箱子或菜单时仍可进行走动和跳跃。

High Jump

• 跳得比正常更高。
• 用于跨越高障碍或快速到达高处。

Jesus

• 在水面或熔岩上行走。
• 不会下沉，可像在地面一样移动。

Long Jump

• 一次性跳跃更远的距离。
• 在 PvP 或跑酷中跨越宽阔空隙。

No Fall

• 阻止坠落伤害。
• 在高处落下时取消或修改坠落数据。

No Slow

• 防止在特定状态下减速。
• 在使用物品、处于蛛网或灵魂沙上时保持正常速度。

Parkour

• 自动进行跑酷动作。
• 检测到边缘时自动跳跃以跨越空隙。

Reverse Step

• 更快地下落到低处。
• 在边缘自动加速下降。

Safe Walk

• 防止从方块边缘掉落。
• 类似潜行状态，接近边缘时自动停下。

Scaffold

• 自动在脚下或前方放置方块。
• 在行走中快速搭桥或垂直上升。

Stippy

• 改变方块的摩擦水平。

Sneak

• 自动潜行。
• 可持续保持潜行状态以避免掉落或降低被发现概率。

Speed

• 提高玩家的移动速度。
• 在地面或空中加快行走与奔跑速度。

Spider

• 沿墙壁垂直攀爬。
• 像蜘蛛一样无障碍爬上方块。

Sprint

• 自动冲刺。
• 保持最高移动速度而无需手动按键。

Step

• 自动跨越更高的方块。
• 无需跳跃即可上 1 格以上的台阶。

Trident Boost

• 使用三叉戟提供额外推进力。
• 在水中或雨天利用激流附魔快速加速。

Velocity

• 修改或减少击退效果。
• 在受到攻击时降低被击退的距离或方向。

Render(渲染类)

Better Tab

• 优化玩家列表界面显示。
• 显示更多玩家信息或自定义样式。

Better Tooltips

• 改进物品提示信息显示。
• 在悬停物品时显示额外数据或更清晰的界面。

Block Esp

• 高亮显示特定方块。
• 用于标记矿石、箱子或自定义方块。

Block Selection

• 自定义方块选中框样式。
• 改变选中方块的高亮边框颜色或形状。

Blur

• 在打开界面时添加背景模糊效果。
• 让界面与游戏背景分离更清晰。

Boss Stack

• 合并相同 Boss 血条显示。
• 多个相同 Boss 时只显示一个血条。

Breadcrumbs

• 在地面留下移动轨迹。
• 用于标记自己走过的路径。

Break Indicators

• 显示方块破坏进度。
• 在破坏方块时提供可视化进度条。

Camera Tweaks

• 调整摄像机控制方式。
• 允许平滑旋转、缩放或自定义视角。

Chams

• 用特殊材质高亮实体。
• 通过墙壁或障碍物仍可看到实体。

City Esp

• 可能与水晶战有关。
• 不玩PVP，不清楚。欢迎补充。

Entity Owner

• 显示实体的拥有者信息。
• 用于区分坐骑、宠物等归属。

Esp

• 高亮显示实体。
• 通过墙体可见玩家、怪物或其他目标。

Free Look

• 独立移动视角而不改变玩家朝向。
• 用于观察周围环境而不影响行走方向。

Freecam

• 分离视角与玩家位置。
• 允许在不移动角色的情况下自由飞行查看环境。

Fullbright

• 提升亮度到最高。
• 在黑暗环境中保持可见度。

Hand View

• 调整第一人称手部模型位置。
• 自定义手部的显示大小或角度。

Hole Esp

• 高亮显示坑洞位置。
• 在 PvP 中标记可利用的防御或陷阱点。

Item Highlight

• 高亮显示掉落物品。
• 更容易在地面找到特定物品。

Item Physics

• 改变掉落物的物理效果。
• 使物品在地面倾斜或滚动。

Light Overlay

• 显示方块的光照等级。
• 用于检查怪物生成点。

Logout Spots

• 标记玩家下线的位置。
• 在地图上显示玩家退出时的坐标。

Marker

• 在世界中放置标记点/图形。

Nametags

• 修改或增强玩家名称标签显示。
• 可显示更远距离或附加信息。

No Render

• 阻止渲染特定元素。
• 隐藏火焰、粒子效果或实体模型。

Pop Chams

• 在图腾触发时高亮显示玩家。
• 在 PvP 中标记敌人触发图腾的瞬间。

Storage Esp

• 高亮显示储物方块。
• 显示箱子、潜影盒、末影箱位置。

Time Changer

• 修改客户端时间。
• 自定义世界的昼夜显示效果。

Tracers

• 从玩家到目标画出指引线。
• 用于快速找到实体位置。

Trail

• 在玩家移动时绘制尾迹。
• 显示彩色轨迹线条。

Trojectories

• 显示投掷物的轨迹预测。
• 用于弓箭、雪球、三叉戟等。

Tunnel Esp

• 高亮显示地下通道。
• 用于定位矿道或隧道结构。

Void Esp

• 高亮显示虚空边界。
• 在建造或探索时避免跌落。

Wall Hack

• 穿透墙体查看实体与方块。
• 用于发现隐藏的玩家或资源。

Waypoints

• 设置并显示地图标记。
• 显示目标的距离与方向。

Xray

• 过滤掉不必要的方块以显示资源。
• 用于快速寻找矿石、地牢或其他方块。

Zoom

• 放大视野范围中心。
• 便于远距离观察目标。

World(世界类)

Ambience

• 修改世界环境氛围。
• 调整颜色、光照或天气效果。

Auto Breed

• 自动为动物繁殖。
• 在检测到食物时自动喂养配对。

Auto Brewer

• 自动酿造药水。
• 按顺序放置材料并完成酿造过程。

Auto Mount

• 自动骑乘坐骑或载具。
• 接近目标时自动骑上。

Auto Nametag

• 自动为实体命名。
• 在持有命名牌时靠近目标自动使用。

Auto Shearer

• 自动为羊剪毛。
• 接近羊时自动使用剪刀。

Auto Sign

• 自动放置并填写告示牌。
• 可预设文字内容快速批量放置。

Auto Smelter

• 自动完成熔炉冶炼任务。
• 自动补充燃料与原料。

Build Height

• 允许你在建筑限制处与物体互动。

Collisions

• 显示方块碰撞箱。
• 检测不可见的边界与判定范围。

Echest Farmer

• 自动寻找并破坏末影箱。
• 收集掉落的黑曜石。

Enderman Look

• 自动看向或者躲避末影人。

Flamethrower

• 使用火焰持续攻击目标。
• 持续点燃敌人或环境。

Highway Builder

• 自动建造高速通道。
• 在地狱或主世界长距离铺路。

Liquid Filler

• 自动填充液体。
• 在空洞中填入水或熔岩。

Mount Bypass

• 绕过坐骑上不能放箱子的限制。

No Ghost Blocks

• 移除客户端与服务器不同步的幽灵方块。
• 通过刷新方块状态修复异常。

Nuker

• 快速大范围破坏方块。
• 一次性清理大面积区域。

Packet Mine

• 使用数据包进行方块破坏。
• 可在不连续破坏的情况下直接完成挖掘。

Spawn Proofer

• 自动放置方块或光源防止怪物生成。
• 在建筑范围内进行刷怪点封锁。

StashFinder

• 自动寻找隐藏储物点。
• 探测并标记箱子、潜影盒等位置。

Timer

• 修改客户端游戏速度。
• 加快或减慢游戏内动作。

Vein Miner

• 一次性挖掘整片矿脉。
• 持续破坏相邻同类方块。

Misc(杂项)

Anti Packet Kick

• 阻止因异常数据包被服务器踢出。
• 自动过滤或修正数据包内容。

Auto Reconnect

• 断线后自动重连服务器。
• 可设置延迟或重连次数。

Better Beacons

• 允许切换效果。

Better Chat

• 改进聊天界面显示。
• 支持自定义颜色、格式或过滤信息。

Book Bot

• 自动填写并生成书籍内容。
• 可批量生成预设文本书。

Discord Presence

• 在 Discord 状态中显示游戏信息。
• 展示当前服务器、坐标等数据。

Inventory Tweaks

• 自动整理背包物品。
• 按类别或顺序排列物品。

Message Aura

• 自动在接近玩家时发送消息。
• 用于问候、警告或嘲讽。

Notebot Notifier

• 自动演奏音符盒。
• 需要设置歌曲，但我不会。

Offhand Crash

• 利用副手物品造成客户端或服务器崩溃。
• 通过异常数据触发错误。

Packet Canceller

• 阻止特定数据包的发送或接收。
• 用于避免触发检测或修改交互。

Server Spoof

• 伪装客户端为其他服务器状态。
• 显示与实际不同的服务器信息。

Sound Blocker

• 阻止特定声音播放。
• 静音环境中的特定音效。

Spam

• 自动在聊天中发送消息。
• 可设置重复内容或定时发送。

Swarm

• 远程控制多个 Meteor 客户端。

—— 完。

简介

Meilisearch 是一个开源的轻量级全文搜索引擎，支持中文分词、模糊搜索、拼写纠错等。

与之相似的竞品有：Elasticsearch、Typesense、Algolia等。其中，Elasticsearch 是老牌搜索服务，但是运行起来太笨重了，除非数据量很大，否则其余轻量级的实现要更好。

后两者 Typesense、Algolia 和本文的主角 Meilisearch 都是更轻量级别的存在，但是 Algolia 不开源，只能使用他们的云服务，而我不太喜欢被平台给局限住，所以也放弃了。

Typesense 和 Meilisearch 都是开源的同时也都提供云服务。很可惜，前者的文档集存在 RAM 里，后者则主要放在磁盘里，虽然性能上确实是前者更出色，但是很明显 RAM 可比存储空间贵的多。

另外，Meilisearch 的社区开发环境也更好。截至本文发布，Meilisearch 有52K stars, 296 watching, 2.1K forks, 201 contributors，而 Typesense 只有23.6K stars, 132 watching, 773 forks, 46 contributors。

(另外，Meilisearch还是用我喜欢的Rust写的)

因此，本文主要讲 Meilisearch 的部署与使用。另附我找到的几个比较资料，或许能帮你选择合适自己的服务。

• Algolia vs ElasticSearch vs Meilisearch vs Typesense 之比较 | 日思录
• Meilisearch 与 Typesense - Meilisearch 搜索引擎

部署

Meilisearch 支持下载二进制和 Docker 部署两种方式。

二进制

另外，Meilisearch 还支持一键脚本安装：

curl -L https://install.meilisearch.com | sh

或者手动下载二进制文件：

Releases · meilisearch/meilisearch

下载完后，使用以下方式启动：

./meilisearch --master-key=YourMasterKey

其中，MasterKey 算是一个管理员密码，可以是 16 位以上的 UTF-8 字符串。获取 API 密钥需要通过此Key，访问管理后台也需要。

也可以自定义端口，默认是7700。

./meilisearch --http-addr '0.0.0.0:7700'

Docker

docker run -it --rm \
  -p 7700:7700 \
  getmeili/meilisearch \
  meilisearch --master-key='YourMasterKey' --http-addr '0.0.0.0:7700'

使用

使用也很简单，分4步，分别是查看当前的API Token、设置要搜索的数据类型、写入数据、搜索。
下面会用到很多curl，windows建议用Postman，直接粘贴进去就能解析。

查看当前API Token

curl -X GET 'https://Your_Meili_URL/keys' -H 'Authorization: YourMasterToken'

获取到的结果是：

{
    "results": [
        {
            "name": "Default Search API Key",
            "description": "Use it to search from the frontend",
            "key": "xxxxxxxx",
            "uid": "xxxxxxxx",
            "actions": [
                "search"
            ],
            "indexes": [
                "*"
            ],
            "expiresAt": null,
            "createdAt": "2025-06-25T11:08:45.729263258Z",
            "updatedAt": "2025-06-25T11:08:45.729263258Z"
        },
        {
            "name": "Default Admin API Key",
            "description": "Use it for anything that is not a search operation. Caution! Do not expose it on a public frontend",
            "key": "xxxxxxxx",
            "uid": "xxxxxxxx",
            "actions": [
                "*"
            ],
            "indexes": [
                "*"
            ],
            "expiresAt": null,
            "createdAt": "2025-06-25T11:08:45.726891008Z",
            "updatedAt": "2025-06-25T11:08:45.726891008Z"
        }
    ],
    "offset": 0,
    "limit": 20,
    "total": 2
}

简单来说会给你两个 Token，存在key字段里，上面是搜索用的，下面是管理用的。

设置数据类型

如果你想索引这样的一个东西：

model Post {
  id           Int      @id @default(autoincrement())
  title        String   @db.VarChar(50)
  content      String   @db.VarChar(200)
  userUid      Int?
  createdAt    DateTime @default(now())
  User         User?    @relation(fields: [userUid], references: [uid])
}

它包含一个主键:id，两个你想索引的东西:title,content。
那么，你首先应该创建这个项：

（这里的API Token既可以用MasterKey，也能用Default Admin API Key）

curl -X POST 'https://Your_Meili_URL/indexes' \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{
    "uid": "posts",
    "primaryKey": "id"
}'

结果：

{

    "taskUid": 0,
    "indexUid": "posts",
    "status": "enqueued",
    "type": "indexCreation",
    "enqueuedAt": "2025-06-25T12:37:59.414437837Z"

}

然后，设置可被搜索的字段：

curl -X PUT 'https://Your_Meili_URL/indexes/posts/settings/searchable-attributes' \
  -H 'Authorization: Bearer API_KEY' \
  -H 'Content-Type: application/json' \
  --data '[
    "title", "content"
  ]'

你也可以设置一些可以用于排序的字段：

curl -X PUT 'https://Your_Meili_URL/indexes/posts/settings/sortable-attributes' \
  -H 'Authorization: Bearer API_KEY' \
  -H 'Content-Type: application/json' \
  --data '["createdAt"]'

类似的，设置用于过滤的字段：

curl -X PUT 'https://Your_Meili_URL/indexes/posts/settings/filterable-attributes' \
  -H 'Authorization: Bearer API_KEY' \
  -H 'Content-Type: application/json' \
  --data '["userUid"]'

写入数据

现在就可以写入数据了。可以用curl，或者是官方SDK：

curl -X POST 'https://Your_Meili_URL/indexes/posts/documents' \
  -H 'Authorization: Bearer API_KEY' \
  -H 'Content-Type: application/json' \
  --data '[
    {
      "id": 1,
      "createdAt": "2025-06-25T00:00:00Z",
      "title": "中文标题",
      "content": "中文内容",
      "userUid": 1,
    }
  ]'

import { MeiliSearch } from 'meilisearch';
import { Post } from '@/generated/prisma';

const client = new MeiliSearch({
  host: process.env.MEILI_HOST || "",
  apiKey: process.env.MEILI_API_KEY, 
})

const index = client.index('posts')

async function addSingleDocument(post: Post) {
  await index.addDocuments([post])
}

await addSingleDocument(post)

搜索

搜索也是，可以用curl，或者是官方SDK：

curl -X POST 'https://Your_Meili_URL/indexes/posts/search' \
  -H 'Authorization: Bearer API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
    "q": "关键词",
    "limit": 10,
    "offset": 0,
    "filter": "userUid = 1 AND title = xxx",
    "sort": ["createdAt:desc"]
}'

import { MeiliSearch } from 'meilisearch';

const client = new MeiliSearch({
  host: process.env.MEILI_HOST || "",
  apiKey: process.env.MEILI_API_KEY, 
})

async function searchPosts(query) {
  const index = client.index('posts')
  const result = await index.search(query, {
    limit: 10
  })
  console.log(result.hits)
}

searchPosts('中文')

前言

最近没什么事做，也懒得再写博客的新内容了，于是打算做个新东西。

想来想去，似乎自己没找到什么好用的倒计时器，于是自己就写了一个。

这里也不写什么技术细节了，大致看下效果就好。

预览

TimePulse - 现代化倒计时(https://timepulse.ravelloh.top/)

Github: RavelloH/TimePulse: 致力于成为最漂亮的倒计时应用。 TimePulse 是一个具有现代化 UI 和交互的倒计时网页应用，支持多计时器管理、数据分享、数据同步、全屏展示等功能。采用玻璃态设计和流畅动画效果，提供极佳的视觉体验。

功能

核心功能

• 支持多个计时器的创建和管理
• 数据本地存储与云端同步
• 支持生成分享链接和二维码
• 支持全屏展示模式
• 智能识别常用节假日
• 支持PWA，可安装到主屏幕并离线使用

视觉和交互

• 精美的玻璃态设计和流畅动效
• 自适应模糊渐变背景，随主题色变化
• 暗色/亮色主题自动切换
• 完全响应式设计，适配各种设备

新增特性

• 自定义滚动条与滚动进度指示器，与主题色联动
• PWA功能支持，可作为独立应用安装到设备
• 离线访问支持，无需网络也能使用核心功能
• 优化的渐变背景效果，解决色彩断层问题
• 自定义下拉菜单组件，完美适配明暗两种模式
• 支持键盘导航的无障碍交互体验
• 滚动触发区优化，改善移动设备触控体验

技术

技术方面我觉得有价值的不算多，主要也就是个时间处理和背景设计让我花了点时间。

目前考虑到的节日放在context/TimerContext中，具体来说，只有以下节日:

// 生成固定日期的节日列表，考虑时区调整
const generateFixedHolidays = (year) => {
  // 获取用户时区偏移量（分钟）
  const userTimezoneOffsetMinutes = new Date().getTimezoneOffset();
  // UTC+0 时区和用户时区的差异小时数（注意符号相反）
  const userTimezoneOffsetHours = -userTimezoneOffsetMinutes / 60;
  
  // 创建时区补偿函数
  const createDateWithOffset = (monthIndex, day) => {
    // 创建UTC时间
    const date = new Date(Date.UTC(year, monthIndex, day));
  
    // 格式化为ISO字符串，保留T00:00:00Z的UTC标志
    return date.toISOString();
  };
  
  return [
    // 国际节日 - 日期固定
    { name: `${year}年元旦`, date: createDateWithOffset(0, 1), color: '#1890FF' },
    { name: `${year}年情人节`, date: createDateWithOffset(1, 14), color: '#EB2F96' },
    { name: `${year}年妇女节`, date: createDateWithOffset(2, 8), color: '#C71585' },
    { name: `${year}年植树节`, date: createDateWithOffset(2, 12), color: '#52C41A' },
    { name: `${year}年愚人节`, date: createDateWithOffset(3, 1), color: '#722ED1' },
    { name: `${year}年青年节`, date: createDateWithOffset(4, 4), color: '#722ED1' },
    { name: `${year}年劳动节`, date: createDateWithOffset(4, 1), color: '#FA8C16' },
    { name: `${year}年清明节`, date: getQingmingDate(year).toISOString(), color: '#228B22' },
    { name: `${year}年儿童节`, date: createDateWithOffset(5, 1), color: '#13C2C2' },
    { name: `${year}年建党节`, date: createDateWithOffset(6, 1), color: '#FF0000' },
    { name: `${year}年建军节`, date: createDateWithOffset(7, 1), color: '#CF1322' },
    { name: `${year}年教师节`, date: createDateWithOffset(8, 10), color: '#096DD9' },
    { name: `${year}年国庆节`, date: createDateWithOffset(9, 1), color: '#FF4D4F' },
    { name: `${year}年万圣节`, date: createDateWithOffset(9, 31), color: '#FF7A45' },
    { name: `${year}年平安夜`, date: createDateWithOffset(11, 24), color: '#36CFC9' },
    { name: `${year}年圣诞节`, date: createDateWithOffset(11, 25), color: '#F759AB' },
  ];
};

// 计算动态节日日期，也考虑时区
const calculateDynamicHolidays = (year) => {
  const holidays = [];
  
  // 获取用户时区的偏移量
  const userTimezoneOffsetMinutes = new Date().getTimezoneOffset();
  const userTimezoneOffsetHours = -userTimezoneOffsetMinutes / 60;
  
  // 创建ISO格式的UTC日期字符串
  const createISODate = (date) => {
    return date.toISOString();
  };
  
  // 母亲节 - 5月第二个星期日
  const firstDayOfMay = new Date(Date.UTC(year, 4, 1));
  const motherDayDay = firstDayOfMay.getUTCDay(); // 获取星期几
  const daysUntilSecondSunday = (7 - motherDayDay) % 7 + 7; // 到第二个星期日的天数
  const motherDayDate = new Date(Date.UTC(year, 4, 1 + daysUntilSecondSunday)); 
  holidays.push({
    name: `${year}年母亲节`,
    date: createISODate(motherDayDate),
    color: '#F759AB'
  });
  
  // 父亲节 - 6月第三个星期日
  const firstDayOfJune = new Date(Date.UTC(year, 5, 1));
  const fatherDayDay = firstDayOfJune.getUTCDay(); // 获取星期几
  const daysUntilThirdSunday = (7 - fatherDayDay) % 7 + 14; // 到第三个星期日的天数
  const fatherDayDate = new Date(Date.UTC(year, 5, 1 + daysUntilThirdSunday)); 
  holidays.push({
    name: `${year}年父亲节`,
    date: createISODate(fatherDayDate),
    color: '#1890FF'
  });
  
  // 感恩节 - 11月第四个星期四
  const firstDayOfNovember = new Date(Date.UTC(year, 10, 1));
  const thanksgivingDayDay = firstDayOfNovember.getUTCDay(); // 获取星期几
  const daysToThursday = (4 + 7 - thanksgivingDayDay) % 7; // 到第一个星期四的天数
  const thanksgivingDayDate = new Date(Date.UTC(year, 10, 1 + daysToThursday + 21)); // 加21天到第四个星期四
  holidays.push({
    name: `${year}年感恩节`,
    date: createISODate(thanksgivingDayDate),
    color: '#FAAD14'
  });
  
  return holidays;
};

// 添加农历节日转换函数
const getChineseFestivals = (year) => {
  const lunarHolidays = [];
  const holidaysMapping = [
    { name: `${year}年春节`, lunarMonth: 1, lunarDay: 1, color: '#FF0000' },
    { name: `${year}年元宵节`, lunarMonth: 1, lunarDay: 15, color: '#FF6347' },
    { name: `${year}年端午节`, lunarMonth: 5, lunarDay: 5, color: '#32CD32' },
    { name: `${year}年七夕节`, lunarMonth: 7, lunarDay: 7, color: '#FF1493' },
    { name: `${year}年中元节`, lunarMonth: 7, lunarDay: 15, color: '#708090' },
    { name: `${year}年中秋节`, lunarMonth: 8, lunarDay: 15, color: '#FFA500' },
    { name: `${year}年重阳节`, lunarMonth: 9, lunarDay: 9, color: '#800080' },
    { name: `${year}年腊八节`, lunarMonth: 12, lunarDay: 8, color: '#8B4513' },
  ];
  
  holidaysMapping.forEach(holiday => {
    // 使用 solarlunar 将农历日期转换为公历日期
    const solarDate = solarlunar.lunar2solar(year, holiday.lunarMonth, holiday.lunarDay, false);
    // 构造 ISO 格式日期字符串，注意月-1
    const date = new Date(Date.UTC(solarDate.cYear, solarDate.cMonth - 1, solarDate.cDay)).toISOString();
    lunarHolidays.push({
      name: holiday.name,
      date: date,
      color: holiday.color
    });
  });
  
  return lunarHolidays;
};

一般来说这些已经够了，你也可以直接拿这部分成品节日日期生成器自己用。

另外比较有意思的是Background，文件在components/Background/GradientBackground.js。

这里其实做到了一种动态化的背景效果，实现方式也比较取巧，是直接在高斯模糊后面加上几个半透明圆，赋予其不同的位置、初速度、颜色，让他们自由组合，效果就已经不错了。

import { useRef, useEffect, useState } from 'react';
import { motion, AnimatePresence } from 'framer-motion';
import { useTimers } from '../../context/TimerContext';
import { useTheme } from '../../context/ThemeContext';

export default function GradientBackground() {
  const { getActiveTimer, activeTimerId } = useTimers();
  const { theme } = useTheme();
  const [circles, setCircles] = useState([]);
  const [prevTimerId, setPrevTimerId] = useState(null);
  const containerRef = useRef(null);
  const activeTimer = getActiveTimer();
  const [isSafari, setIsSafari] = useState(false);
  
  // 检测Safari浏览器
  useEffect(() => {
    // 检测Safari浏览器
    const isSafariBrowser = 
      navigator.userAgent.indexOf('Safari') !== -1 && 
      navigator.userAgent.indexOf('Chrome') === -1;
  
    // 检测iOS设备
    const isIOS = /iPad|iPhone|iPod/.test(navigator.userAgent) && !window.MSStream;
  
    setIsSafari(isSafariBrowser || isIOS);
  }, []);
  
  // 生成渐变圆圈 - 针对Safari减少圆圈数量和动画复杂度
  useEffect(() => {
    // 检查计时器是否变化
    const isNewTimer = activeTimerId !== prevTimerId;
    if (isNewTimer) {
      setPrevTimerId(activeTimerId);
    }
  
    // 基于活动计时器的颜色生成颜色
    const baseColor = activeTimer?.color || '#0ea5e9';
    const colors = generateColors(baseColor, theme === 'dark');
  
    // 针对Safari减少圆圈数量
    const circleCount = 5
  
    // 生成或更新圆圈配置
    if (circles.length === 0 || isNewTimer) {
      // 如果是新计时器或初始化，创建新圆圈
      const newCircles = Array.from({ length: circleCount }, (_, i) => ({
        id: i,
        x: Math.random() * 100 - 30 + Math.random() * 40,
        y: Math.random() * 100 - 30 + Math.random() * 40,
        size: 30 + Math.random() * 40,
        speedX: (Math.random() - 0.5) * (isSafari ? 0.01 : 0.03), // 降低Safari中的速度
        speedY: (Math.random() - 0.5) * (isSafari ? 0.01 : 0.03), // 降低Safari中的速度
        color: colors[i % colors.length],
        blur: isSafari ? 40 : (60 + Math.random() * 40), // 减少Safari中的模糊强度
        opacity: 0.3 + Math.random() * (isSafari ? 0.2 : 0.3) // 降低Safari中的透明度变化
      }));
      setCircles(newCircles);
    } else if (activeTimer) {
      // 如果计时器颜色变化，平滑过渡圆圈颜色
      setCircles(prev => prev.map((circle, i) => ({
        ...circle,
        // 使用过渡这里，而不是闪烁效果
        color: colors[i % colors.length]
      })));
    }
  }, [activeTimerId, theme, activeTimer, isSafari]);
  
  // 根据基础颜色生成一组和谐的颜色
  const generateColors = (baseColor, isDark) => {
    // 解析颜色
    let r, g, b;
  
    if (baseColor.startsWith('#')) {
      const hex = baseColor.slice(1);
      r = parseInt(hex.slice(0, 2), 16);
      g = parseInt(hex.slice(2, 4), 16);
      b = parseInt(hex.slice(4, 6), 16);
    } else {
      // 默认颜色
      r = 14;
      g = 165;
      b = 233;
    }
  
    // 生成颜色变体
    return [
      `rgba(${r}, ${g}, ${b}, 0.5)`, // 原色
      `rgba(${r * 0.8}, ${g * 1.1}, ${b * 1.2}, 0.5)`, // 变体1
      `rgba(${r * 1.2}, ${g * 0.8}, ${b * 0.9}, 0.5)`, // 变体2
      `rgba(${r * 0.9}, ${g * 0.9}, ${b * 1.3}, 0.5)`, // 变体3
      `rgba(${r * 1.1}, ${g * 1.2}, ${b * 0.8}, 0.5)`, // 变体4
      `rgba(${r * 1.3}, ${g * 0.9}, ${b * 0.9}, 0.5)`  // 变体5
    ];
  };
  
  return (
    <div className="fixed inset-0 overflow-hidden z-0 pointer-events-none">
      <AnimatePresence>
        {circles.map(circle => (
          <motion.div
            key={`circle-${circle.id}-${activeTimerId || 'default'}`}
            className="moving-circle absolute"
            initial={{ 
              left: `${circle.x}vw`,
              top: `${circle.y}vh`,
              width: `${circle.size}vw`,
              height: `${circle.size}vw`,
              opacity: 0 
            }}
            animate={{
              left: [`${circle.x}vw`, `${circle.x + circle.speedX * 100}vw`],
              top: [`${circle.y}vh`, `${circle.y + circle.speedY * 100}vh`],
              backgroundColor: circle.color,
              filter: `blur(${circle.blur}px)`,
              opacity: circle.opacity
            }}
            transition={{
              left: { duration: isSafari ? 30 : 20, ease: "linear", repeat: Infinity, repeatType: "reverse" },
              top: { duration: isSafari ? 30 : 20, ease: "linear", repeat: Infinity, repeatType: "reverse" },
              // 增加Safari中的过渡持续时间，减少更新频率
              backgroundColor: { duration: isSafari ? 3.5 : 2.5, ease: "easeOut" },
              opacity: { duration: isSafari ? 1.2 : 0.8 }
            }}
            style={{
              // 添加硬件加速属性
              WebkitTransform: "translateZ(0)",
              transform: "translateZ(0)",
              willChange: "transform"
            }}
          />
        ))}
      </AnimatePresence>
  
      {/* 移除闪烁动画，替换为以下更平滑的过渡效果 */}
      {activeTimerId !== prevTimerId && prevTimerId !== null && (
        <motion.div
          className="absolute inset-0 z-0 pointer-events-none"
          // 背景使用径向渐变，从中心向外扩散，效果更自然
          style={{ 
            background: `radial-gradient(circle at center, ${activeTimer?.color || '#0ea5e9'}05 0%, transparent 70%)` 
          }}
          initial={{ opacity: 0 }}
          animate={{ opacity: 0.5 }}
          exit={{ opacity: 0 }}
          transition={{ duration: 2.5, ease: "easeOut" }}
          onAnimationComplete={() => setPrevTimerId(activeTimerId)}
        />
      )}
    </div>
  );
}

前言

目前博客已经支持动态页面重部署，简单来说就是写完文章发布后，不用再去Redeploy了，直接就能在访问的时候完成构建，并且保留构建成果作为缓存。

从这个角度来说，现在的RTheme才是个比较理想的动态站，至少写文章变的简单多了——现在只需要编辑、保存，即可。

实际上算是比较简单的，只是用了Nextjs 14里面的新机制Server Action，允许你在服务器端执行代码，并直接调用它来重新验证页面缓存。

实现

非常简单，例如:

// app/api/_utils/actions.ts
'use server';

import { revalidatePath } from 'next/cache';

export async function refreshPosts() {
    revalidatePath('/posts'); // 重新渲染 `/posts` 页面
    revalidatePath('/posts/[name]'); // 重新渲染所有`/posts/xxx`页面
}

// 文章编辑/修改api
import { NextResponse } from 'next/server';
import prisma from '@/app/api/_utils/prisma';
import { refreshPosts } from '@/app/api/_utils/actions';

export async function POST(req: Request) {
    try {
        const data = await req.json();
        const post = await prisma.post.create({
            data: {
                title: data.title,
                name: data.name,
                published: true,
                createdAt: new Date(),
            },
        });

        // 文章添加成功后，刷新博客页面
        await refreshPosts();

        return NextResponse.json({ success: true, post });
    } catch (error) {
        return NextResponse.json({ success: false, error: error.message }, { status: 500 });
    }
}

实际上如果你的其余文章内容与修改无关的话，你可以自己让调用Server Actions的组件自己传参来刷新特定页面而非所有博客，毕竟如果真全刷新了回到无缓存状态，那么第一次加载的速度还是非常慢的。

同理，只要是个page.tsx就都能通过Server Actions进行刷新，也包括RSS和Sitemap。

前言

在某些公用网络环境中，你可能会面临网络安全泄露的风险。本文使用Wireshark来分析你的设备是否存在被监听的风险。

这里以移动设备为例，实际上其余设备均可用此方法分析。你需要有无线网卡的计算机以用于为其他设备提供网络连接。

准备工作

你需要：

• 一台计算机(带有无线网卡)
• Wireshark
• 其余需要分析的设备

分析

筛选目标设备

1. 首先，将你需要分析的设备连接至你的电脑热点
2. 在你的设备上检查其分配到的IP地址
3. 在你的计算机中，使用cmd输入ipconfig以查看所有网卡的信息
4. 找到其中有你所需分析设备的网卡。
5. 在Wireshark中选择此网卡监听。

例如，我的设备IP为192.168.137.199，通过ipconfig发现其被无线局域网适配器 本地连接* 2管理，那么就应该在Wireshark中选择本地连接* 2。

检查DNS是否加密

通常情况下，你的DNS未经加密，由明文直接使用udp协议传输，这会带来巨大的安全隐患。你可以在Wireshark中，筛选并查看这些未经加密的流量。

使用你的设备访问一定数量的资源后，在你的Wireshark中以以下格式筛选：

ip.addr == [目标设备IP] && udp.port == 53

如发现类似上图的数据，说明你的DNS未经加密，可能存在泄露隐私的风险。你可以使用DoT/DoH来加密。例如，在Quantumult X的DNS配置中这样设置：

[dns]
prefer-doh3
doh-server = https://223.5.5.5/dns-query, https://223.6.6.6/dns-query,https://1.12.12.12/dns-query,https://8.8.8.8/dns-query,https://208.67.222.222/dns-query,https://208.67.220.220/dns-query,https://208.67.222.123/dns-query
no-system

检查SNI泄露

SNI（Server Name Indication，服务器名称指示）是TLS（传输层安全协议）扩展的一部分。它的作用是在TLS握手时，客户端告诉服务器它想访问的具体域名。

很遗憾，即使DNS加密，在未使用代理的情况下，你所访问的资源域名仍可被监测。

你可以在Wireshark中以以下方式筛选所有Client Hello包，查看其泄露情况。

ip.addr == [目标设备IP] && tls.handshake.type == 1 && tcp

如上图所示，如果你发现了任何你不想让其他人看到的域名，说明你的代理分流工作未到位，设置此域名走代理即可。

MITM

常用的网络监听应该就是以上两种方式，不过也不排除有些极端环境可能会MITM，虽然99%是用不上的。

MITM的特点是需要伪造证书，没什么很好的检查方式，不过你也可以通过查看Server端发过来的证书的Issuer来确认正式是否由知名CA签署。

ip.dst == [目标设备IP] && tls.handshake.certificates

前言

有的时候指向外链的超链接的显示文字可能根本不能让你了解到这是来源于哪个站点的，鼠标移上去看左下角又不太优雅，于是写了个这样的预览框。

效果

当鼠标悬停在 target="_blank" 的超链接上时，会出现一个带模糊背景的弹出窗口，显示网站的主域名和完整 URL，同时附带一个提醒，告知该链接为外部链接。同时会加载目标页面的截图，获取到截图后根据图片的中心色，自动选择字体颜色(黑/白)。

你也可以在下方这个外链上自己试试:

RTheme/src/components/LinkPreview.jsx at main · RavelloH/RTheme

使用

在所需的页面引入下方的jsx即可，你可以修改下方const link = e.target.closest('article a[target="_blank"]');的定义来自定义哪些元素要有此效果。默认是article元素下的具有target="_blank"的标签。

另，截图功能依靠Lete114/WebStack-Screenshot: 📸 Website Screenshot API，这里是用到我部署在Vercel上的APIhttps://screenshot.ravelloh.top，你也可以自己部署一个把下面的api链接换了。

截图为了加快加载，默认缓存2592000秒(30天)。

'use client';

import { useEffect } from 'react';

const styles = {
    preview: {
        position: 'absolute',
        background: 'rgba(0, 0, 0, 0.65)',
        backdropFilter: 'blur(8px)',
        WebkitBackdropFilter: 'blur(8px)',
        backgroundSize: 'cover',
        backgroundPosition: 'center',
        backgroundRepeat: 'no-repeat',
        border: '1px solid rgba(255, 255, 255, 0.1)',
        borderRadius: '12px',
        padding: '16px',
        maxWidth: '400px',
        width: 'calc(100vw - 32px)',
        boxShadow: '0 4px 12px rgba(0, 0, 0, 0.2)',
        zIndex: 1000,
        fontSize: '14px',
        transition: 'opacity 0.3s ease',
        opacity: 0,
        pointerEvents: 'none',
        color: '#fff',
        textShadow: '0 1px 3px rgba(0, 0, 0, 0.9), 0 2px 6px rgba(0, 0, 0, 0.9)',
        overflow: 'hidden',
        '&.loading': {
            backgroundImage: 'none !important',
            animation: 'shimmer 2.5s infinite linear',
            backgroundSize: '400% 100%',
            background:
                'linear-gradient(90deg, rgba(255,255,255,0.06) 0%, rgba(255,255,255,0.12) 50%, rgba(255,255,255,0.06) 100%)',
        },
    },
    header: {
        display: 'flex',
        alignItems: 'center',
        gap: '8px',
        marginBottom: '12px',
        lineHeight: '20px',
        textShadow: '0 1px 3px rgba(0, 0, 0, 0.9), 0 2px 6px rgba(0, 0, 0, 0.9)',
    },
    title: {
        margin: '0',
        fontSize: '16px',
        fontWeight: 'bold',
        color: '#fff',
        lineHeight: '20px',
        display: 'flex',
        alignItems: 'center',
        textShadow: '0 1px 3px rgba(0, 0, 0, 0.9), 0 2px 6px rgba(0, 0, 0, 0.9)',
        overflow: 'hidden',
        textOverflow: 'ellipsis',
        whiteSpace: 'nowrap',
        maxWidth: '100%',
    },
    url: {
        color: 'rgba(255, 255, 255, 0.7)',
        fontSize: '13px',
        marginBottom: '12px',
        wordBreak: 'break-all',
        textShadow: '0 1px 3px rgba(0, 0, 0, 0.9), 0 2px 6px rgba(0, 0, 0, 0.9)',
        overflow: 'hidden',
        textOverflow: 'ellipsis',
        display: '-webkit-box',
        '-webkit-line-clamp': '2',
        '-webkit-box-orient': 'vertical',
        whiteSpace: 'normal',
        maxHeight: '2.6em',
    },
    warning: {
        display: 'flex',
        alignItems: 'center',
        gap: '6px',
        color: 'rgba(255, 255, 255, 0.6)',
        fontSize: '12px',
        paddingTop: '12px',
        borderTop: '1px solid rgba(255, 255, 255, 0.1)',
        textShadow: '0 1px 3px rgba(0, 0, 0, 0.9), 0 2px 6px rgba(0, 0, 0, 0.9)',
    },
};

export default function LinkPreview() {
    useEffect(() => {
        let currentPreview = null;
        let timeout = null;

        const createPreview = (link) => {
            const preview = document.createElement('div');
            preview.className = 'link-preview loading';
            const bgImageUrl = `https://screenshot.ravelloh.top/?url=${encodeURIComponent(
                link.href,
            )}&viewport=1600x800&cache=2592000`;

            Object.assign(preview.style, styles.preview);

            const url = link.href;
            const hostname = new URL(url).hostname;

            preview.innerHTML = `
                <div style="${Object.entries(styles.header)
                    .map(([k, v]) => `${k}:${v}`)
                    .join(';')}">
                    <h4 style="${Object.entries(styles.title)
                        .map(([k, v]) => `${k}:${v}`)
                        .join(';')}">
                        ${hostname}
                    </h4>
                </div>
                <div style="${Object.entries(styles.url)
                    .map(([k, v]) => `${k}:${v}`)
                    .join(';')}">
                    ${url}
                </div>
                <div style="${Object.entries(styles.warning)
                    .map(([k, v]) => `${k}:${v}`)
                    .join(';')}">
                    <span class="i_mini ri-error-warning-fill"></span>
                    非本站站内链接，请注意外部链接的安全性
                </div>
            `;

            const img = new Image();
            img.crossOrigin = 'Anonymous';
            img.onload = () => {
                const canvas = document.createElement('canvas');
                const ctx = canvas.getContext('2d');
                canvas.width = img.width;
                canvas.height = img.height;
                ctx.drawImage(img, 0, 0);

                // 获取图片中心区域的亮度
                const imageData = ctx.getImageData(
                    img.width * 0.25,
                    img.height * 0.25,
                    img.width * 0.5,
                    img.height * 0.5,
                );
                const data = imageData.data;
                let brightness = 0;

                for (let i = 0; i < data.length; i += 4) {
                    brightness += data[i] * 0.299 + data[i + 1] * 0.587 + data[i + 2] * 0.114;
                }
                brightness = brightness / (data.length / 4) / 255;

                const textColor = brightness > 0.6 ? '#000' : '#fff';
                const textShadow =
                    brightness > 0.6
                        ? '0 1px 3px rgba(255, 255, 255, 0.9), 0 2px 6px rgba(255, 255, 255, 0.9)'
                        : '0 1px 3px rgba(0, 0, 0, 0.9), 0 2px 6px rgba(0, 0, 0, 0.9)';

                preview.querySelectorAll('div, h4').forEach((el) => {
                    el.style.color = textColor;
                    el.style.textShadow = textShadow;
                });

                preview.classList.remove('loading');
                preview.style.backgroundImage = `url("${bgImageUrl}")`;
            };
            img.src = bgImageUrl;

            return preview;
        };

        const showPreview = (link) => {
            const rect = link.getBoundingClientRect();
            const preview = createPreview(link);
            document.body.appendChild(preview);

            const previewRect = preview.getBoundingClientRect();
            const top = rect.top - previewRect.height - 10;

            let left = rect.left + (rect.width - previewRect.width) / 2;
            const minLeft = 16;
            const maxLeft = window.innerWidth - previewRect.width - 16;
            left = Math.max(minLeft, Math.min(left, maxLeft));

            Object.assign(preview.style, {
                top: `${top}px`,
                left: `${left}px`,
            });

            requestAnimationFrame(() => {
                preview.style.opacity = '1';
            });

            currentPreview = preview;
        };

        const hidePreview = () => {
            if (currentPreview) {
                currentPreview.style.opacity = '0';
                setTimeout(() => {
                    currentPreview?.remove();
                    currentPreview = null;
                }, 300);
            }
        };

        const handleMouseEnter = (e) => {
            const link = e.target.closest('article a[target="_blank"]');
            if (link) {
                timeout = setTimeout(() => {
                    showPreview(link);
                }, 300);
            }
        };

        const handleMouseLeave = () => {
            if (timeout) {
                clearTimeout(timeout);
                timeout = null;
            }
            hidePreview();
        };

        document.addEventListener('mouseover', handleMouseEnter);
        document.addEventListener('mouseout', handleMouseLeave);

        return () => {
            document.removeEventListener('mouseover', handleMouseEnter);
            document.removeEventListener('mouseout', handleMouseLeave);
            if (currentPreview) {
                currentPreview.remove();
            }
        };
    }, []);

    return null;
}

mini版

如果你只需要显示个背景模糊框而不需要截图，那么用下面这个就行。

'use client';

import { useEffect } from 'react';

const styles = {
    preview: {
        position: 'absolute',
        background: 'rgba(0, 0, 0, 0.65)',
        backdropFilter: 'blur(8px)',
        WebkitBackdropFilter: 'blur(8px)',
        border: '1px solid rgba(255, 255, 255, 0.1)',
        borderRadius: '12px',
        padding: '16px',
        maxWidth: '400px',
        width: 'calc(100vw - 32px)',
        boxShadow: '0 4px 12px rgba(0, 0, 0, 0.2)',
        zIndex: 1000,
        fontSize: '14px',
        transition: 'opacity 0.3s ease',
        opacity: 0,
        pointerEvents: 'none',
        color: '#fff',
    },
    header: {
        display: 'flex',
        alignItems: 'center',
        gap: '8px',
        marginBottom: '12px',
        lineHeight: '20px',
    },
    title: {
        margin: '0',
        fontSize: '16px',
        fontWeight: 'bold',
        color: '#fff',
        lineHeight: '20px',
        display: 'flex',
        alignItems: 'center',
    },
    url: {
        color: 'rgba(255, 255, 255, 0.7)',
        fontSize: '13px',
        marginBottom: '12px',
        wordBreak: 'break-all',
    },
    warning: {
        display: 'flex',
        alignItems: 'center',
        gap: '6px',
        color: 'rgba(255, 255, 255, 0.6)',
        fontSize: '12px',
        paddingTop: '12px',
        borderTop: '1px solid rgba(255, 255, 255, 0.1)',
    },
};

export default function LinkPreview() {
    useEffect(() => {
        let currentPreview = null;
        let timeout = null;

        const createPreview = (link) => {
            const preview = document.createElement('div');
            preview.className = 'link-preview';
            Object.assign(preview.style, styles.preview);

            const url = link.href;
            const hostname = new URL(url).hostname;

            preview.innerHTML = `
                <div style="${Object.entries(styles.header)
                    .map(([k, v]) => `${k}:${v}`)
                    .join(';')}">
                    <h4 style="${Object.entries(styles.title)
                        .map(([k, v]) => `${k}:${v}`)
                        .join(';')}">
                        ${hostname}
                    </h4>
                </div>
                <div style="${Object.entries(styles.url)
                    .map(([k, v]) => `${k}:${v}`)
                    .join(';')}">
                    ${url}
                </div>
                <div style="${Object.entries(styles.warning)
                    .map(([k, v]) => `${k}:${v}`)
                    .join(';')}">
                    <span class="i_mini ri-error-warning-fill"></span>
                    非本站站内链接，请注意外部链接的安全性
                </div>
            `;

            return preview;
        };

        const showPreview = (link) => {
            const rect = link.getBoundingClientRect();
            const preview = createPreview(link);
            document.body.appendChild(preview);

            const previewRect = preview.getBoundingClientRect();
            const top = rect.top - previewRect.height - 10;

            // 修改left计算逻辑，确保不会超出屏幕
            let left = rect.left + (rect.width - previewRect.width) / 2;
            const minLeft = 16; // 左边距
            const maxLeft = window.innerWidth - previewRect.width - 16; // 右边距
            left = Math.max(minLeft, Math.min(left, maxLeft)); // 限制在可视区域内

            Object.assign(preview.style, {
                top: `${top}px`,
                left: `${left}px`,
            });

            requestAnimationFrame(() => {
                preview.style.opacity = '1';
            });

            currentPreview = preview;
        };

        const hidePreview = () => {
            if (currentPreview) {
                currentPreview.style.opacity = '0';
                setTimeout(() => {
                    currentPreview?.remove();
                    currentPreview = null;
                }, 300);
            }
        };

        const handleMouseEnter = (e) => {
            const link = e.target.closest('article a[target="_blank"]');
            if (link) {
                timeout = setTimeout(() => {
                    showPreview(link);
                }, 300);
            }
        };

        const handleMouseLeave = () => {
            if (timeout) {
                clearTimeout(timeout);
                timeout = null;
            }
            hidePreview();
        };

        document.addEventListener('mouseover', handleMouseEnter);
        document.addEventListener('mouseout', handleMouseLeave);

        return () => {
            document.removeEventListener('mouseover', handleMouseEnter);
            document.removeEventListener('mouseout', handleMouseLeave);
            if (currentPreview) {
                currentPreview.remove();
            }
        };
    }, []);

    return null;
}

注意，我这里的图标是用的<span class="i_mini ri-error-warning-fill"></span>来直接显示的，上面每图标库的话不会有图标，你可以换成相应的svg:

<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><path fill="currentColor" d="M12 22C6.477 22 2 17.523 2 12S6.477 2 12 2s10 4.477 10 10s-4.477 10-10 10m-1-7v2h2v-2zm0-8v6h2V7z"></path></svg>

或者在 Icônes 找更多格式。

原理

功能上没什么可说的，只是创建个临时元素而已，下面用AI生成一份说明。

该组件在 useEffect 中为 article 内的 target="_blank" 链接添加鼠标悬停事件。

1. 组件在挂载时使用 useEffect 设置了全局的 mouseover 和 mouseout 事件监听器。

• 当鼠标移到页面中的 article 内部的、target 为 "_blank" 的链接上时，会延时 300 毫秒后调用 showPreview 函数显示预览。
• 当鼠标移出时，清除定时器，并通过 hidePreview 函数隐藏预览。

2. showPreview 函数：

• 通过 createPreview 创建一个预览元素，该元素是一个 div，并应用了一系列内联样式（从 styles 对象中转换而来）。
• 预览内容包括：显示链接的 hostname、完整 url 以及一个警告信息，提示用户这是外部链接。

3. createPreview 函数：

• 创建预览元素，并设置 loading 状态，同时根据链接构造一个远程截图 API 的 URL 作为背景图片地址。
• 创建一个 Image 对象来加载背景图片，加载完成后在 canvas 上绘制图片，并采集中间区域的亮度信息。
• 根据图片亮度调整预览中各个部分的文字颜色和文字阴影，确保无论背景明暗都能清晰显示信息。
• 最后移除 loading 状态，并把背景图片赋值给预览元素。

4. 预览元素的位置计算：

• 根据触发预览的链接元素的边界信息，动态计算预览框的位置，保证不会超出屏幕左右边界。

5. 预览的显示和隐藏：

• 显示时通过 requestAnimationFrame 让预览元素渐显（opacity 从 0 变成 1）。
• 隐藏时先设置 opacity 为 0，然后在 300 毫秒后将预览元素从 DOM 中移除。

6. 清理工作：

• 在组件卸载时，移除所有事件监听器，并清理残留的预览元素，避免内存泄漏。

最近在看访问统计的时候发现来自bing的流量增长了很多，看了一下发现是关于Paper端插件的文章的。

于是开无痕去搜索了一下，发现已经被bing置顶了:

这个倒是确实挺令我意外的，毕竟top域名的权重应该挺低的才对。