余弦の博客

FE Bits Vol.27 | Oxfmt Beta 发布，Chromium「CSS 漏洞」实为 UAF

Sun, 01 Mar 2026 15:21:22 GMT

关于本周刊

本期网址 https://blog.cosine.ren/post/weekly-27

本周刊更新时间期望是在每周天。

推荐订阅本周刊的 RSS。

公众号前端周周谈 FE Bits，点击阅读原文链接可查看原文。

QQ 讨论小群 598022684 / Discord 群

本周刊文章内容同时也开源在 fe-bits-weekly，欢迎关注。

今天是 2026 年 3 月 1 日，星期天。

个人动态

过年放假，给我放爽了，停更的这阵子疯狂写代码，肝项目，现在周刊恢复更新啦～

想说些什么，却又有些不知道该说什么，等我更新年终总结吧（真有人 3 月份才写去年的年终总结啊）（哦原来那个人是我啊.webp）

过完了年，也跳完了槽，在新公司干了一阵子之后，愈发觉得自己的选择没错，这阵子发生了很多～

有关注我的前端频道的应该就能明白我最近在做什么，所以也在这里正儿八经发一下我们公司的招聘。招很多前端，有图像编辑器经验的话更好！岗位都在 JD 里了，二次元浓度越高越好（逃）欢迎佬来撩，远程办公，年限不限，实习兼职都可以，主要看适配程度，感兴趣的欢迎直接邮箱 ball@mewtant.io 投递！备注一下 cos 内推的就行，也欢迎私聊我了解了解情况～

我进来工作的感觉反正是灰常爽的！太二次元了很对我电波！

【我们的产品】我们是一家专注于研究二次元生成式 AI 的创业公司，目前已研发上线的 text-to-image AI 生成和消费平台已成为海外头部产品，用户量和市场占有率迅速增长中。
【我们的资本背景】现已获得 makers fund 等多家一线顶级机构的多轮投资，目前估值上亿美元。
【我们的团队】公司总部位于新加坡，五湖四海的小伙伴同样支持远程办公。公司团队成员背景丰富，技术能力扎实，没有无聊的潜规则，实习小天才和大师傅都能尽情发挥和学习。
【你能得到】获得赛道最前沿技术/产品认知，一起 work on 一个产品，切实体验让想象成为现实的经历，一段有意义且实现自身价值的工作。

JD 相关： job.mewtant.io
公司相关的 pr：曾获红杉投资、估值上亿美元，二次元公司凭动漫向 AI 生图掘金海外

企业文化 Be Like（直接偷偷 saka 发的）

MoePeek

之前 Easydict 经常漏内存太麻了，用久了就卡的要死，然后我的划词翻译需求又其实特别少，正好之前学了点 Swift 就自己过年顺手 vibe 写了一个（

主要自己用，纯 Swift 6 构建，安装体积约 5 MB ，后台运行内存约 50 MB ，很放心的挂后台，如果开 OCR 截图的话运行内存差不多到 100 MB

开源出来欢迎提 Issue ～但是不一定会加新功能了，会修修 bug

这个项目有 PopClip 集成，就在 Release 中，README 里有常见问题说明
成熟方案建议 Bob 或者 clicknow，这几个商业化的项目做的都很成熟

PS：我真的很喜欢 Easydict 但是找他们的内存泄漏问题再改有点难了 hhh 索性 vibe 一个只加自己需要的功能

一款轻量级 macOS 划词翻译工具，纯 Swift 6 开发，安装体积仅 5MB ，后台运行内存稳定约 50MB

GitHub: https://github.com/cosZone/MoePeek

社区动态

React 基金会：由 Linux 基金会托管的 React 新家园：React 官方宣布 React 基金会正式在 Linux 基金会（Linux Foundation）旗下成立，标志着 React 正式脱离 Meta 成为独立的开源项目。
TanStack 团队发布新库 TanStack Hotkeys，解决键盘快捷键开发中常见的跨平台、作用域冲突、输入框聚焦忽略等“小坑”，提供类型安全（Type-safety）、快捷键序列识别、状态追踪及 React 等框架适配器，并集成 Devtools 插件提升开发体验。
Oxfmt Beta：Oxfmt 宣布进入 Beta 阶段，自 Alpha 版本以来，Oxfmt 大幅扩展了功能，包括 100% 兼容 Prettier 的 JavaScript 和 TypeScript 格式化规则、支持多种文件格式（如 JSON, YAML, HTML, CSS 等）、内置 Tailwind CSS 类排序和可配置的导入语句排序功能，并提供了 Node.js API 和广泛的编辑器支持。（开始用好一阵子了，很香）
Claude Code 发布远程控制功能：Claude Code 发布了名为“远程控制”(Remote Control) 的新功能，允许 Max 和 Pro 用户在终端启动任务后，通过手机或网页端继续控制 Claude Code 会话，实现跨设备无缝工作。目前，该功能已向 Max 用户开放，并将很快扩展至 Pro 用户。用户可通过运行 claude rc 命令开始使用。
An Exploit ... in CSS?!：很有意思，这篇文章提到了 Chromium 浏览器中一个被报道为“CSS 漏洞”的零日漏洞 (zero-day exploit) CVE-2026-2441，并澄清了其技术细节，指出恶意并非源于 CSS 本身，而是 Chromium 渲染引擎中一个 Use After Free (UAF) 的内存管理缺陷。

文章

从 instanceof 到 Error.isError：JavaScript 中更安全的错误检查：这篇文章介绍了在 JavaScript 中使用 Error.isError() 代替 instanceof Error 进行错误检查的优势，尤其是在处理跨域（cross-realm）错误时的安全性和可靠性。
构建无懈可击的 React 组件：一位 Vercel 资深工程师分享如何构建能应对真实复杂场景的健壮 React 组件，涵盖服务端渲染（Server Rendering）、水合（Hydration）、多实例、并发渲染（Concurrent Rendering）、组合（Composition）、Portal、View Transition、Activity、数据泄露防护及未来兼容性等现代 React 应用中的关键挑战。
Logo 泛滥问题（及其解决方案）：Sanity 团队开发了 React 组件解决网页中多品牌 Logo 排列时因尺寸、比例与视觉重量不一致导致的“Logo Soup”混乱问题。
你的 JavaScript 清理自身的工作很快就会变得简单很多：JavaScript 即将通过 Explicit Resource Management 提案引入 using 与 [Symbol.dispose]，使资源清理更统一、可靠且自动化。
深入解析 CSS 自定义列表样式指南：本文深入探讨了如何使用 CSS 从基础到高级全面自定义 HTML 列表样式，并兼顾了排版美学与无障碍访问。
Creating Query Abstractions：在 React 开发中，开发者习惯通过封装自定义 Hook 来复用 useQuery 的逻辑。然而作者指出，在结合 TypeScript 时，这种做法不仅会导致类型推断 (Type Inference) 失效，还容易引发复杂的“泛型地狱”。
Zoom!：解析了 CSS zoom 属性在实际布局中的实用性，及其与 transform: scale 的区别。
Remember sprites：2026，重新审视 CSS 图像精灵 (Sprites) 技术，结合 object-fit、object-position 和 step() 动画函数，实现有趣的逐帧动画。
Virtual Scrolling for Billions of Rows — Techniques from HighTable：本文介绍了 <HighTable> React 组件中如何通过五种核心技术实现数十亿行数据的虚拟滚动 (Virtual Scrolling，实现高性能和可访问性。

CSS 新特性

border-shape: the future of the non-rectangular web：本文深入介绍了即将到来的 CSS 属性 border-shape，它将彻底改变构建非矩形网页元素的方式。

趣站

Matthew Pothier 先生的个人作品集网站，融合了色彩在重叠图层中晕染开来的视觉效果：一位电影摄影师极简且具有独特 WebGL 色彩流动效果的个人作品集网站。

站点地址：Matthew Pothier-Cinematographer

Express yourself with Unicode：Kaomoji Cool Club 收集了大量有趣的颜文字 (Kaomoji)，让你用 Unicode 字符表达自我。

工具

Modern CSS Code Snippets：modern-css.com 是一个对比旧有 CSS 技巧与现代原生解决方案的参考网站，帮助开发者摆脱过时方法，利用最新 CSS 特性实现更简洁、高效的网页设计，很实用了，还有 RSS。
Can We Use：canwe.dev 是一个聚合了多种实用网页开发工具的网站，可以帮助开发者快速查询 Can I Use / Can I Stop、电子邮件客户端支持、可访问性信息、Web 平台功能进展及浏览器开发路线图等，为前端开发者提供一站式的信息查询服务。
broz：antfu 出品，一款简洁、无边框的屏幕截图浏览器，npx broz antfu.me 即可使用
SVG Studio，又一款基于浏览器的 SVG 处理工具，集成了优化、调试及修复渲染问题等多种功能。很好用。

Codepen

Flood Above the Floor

See the Pen Eayqjwr by wakana-k (@wakana-k) on CodePen.

步入 Wakana Y.K. 创作的这个 Three.js 场景，你会发现自己置身于一个优雅的房间，积水没过脚踝。环顾四周进行探索，或者思考一下那些精美的装修正遭受着多么严重的水浸破坏。

Sliding border glow on hover for beveled cards

See the Pen EayVXKj by thebabydino (@thebabydino) on CodePen.

Ana Tudor 通过 corner-shape 和 background-clip 展示了现代 CSS 的大师级用法，以此回答了 Reddit 上的一个提问，并为尚不支持这些特性的浏览器提供了回退方案。请查看 Ana 那份注释极其详尽的代码，以了解具体实现细节。

文本特效

https://codepen.io/collection/Poergz

codepen.io

Pedro Ondiviela 分享了一系列醒目的 SVG 滤镜和 CSS 文本效果。每个效果都是可编辑的，因此你可以使用自己的文字进行尝试。

Aerodynamic Typography 空气动力学字体

See the Pen EayBZwy by mike-at-redspace (@mike-at-redspace) on CodePen.

使用鼠标滚轮控制风扇，在这个来自 mike-at-redspace 的有趣 Matter.js Pen 中观看字母飞舞并从墙壁上反弹。

Refs

FE Bits Vol.26 | Gatsby 支持 React 19，Rspress 2.0 发布

Sun, 08 Feb 2026 16:42:38 GMT

关于本周刊

本期网址 https://blog.cosine.ren/post/weekly-26

本周刊更新时间期望是在每周天。

推荐订阅本周刊的 RSS。

公众号前端周周谈 FE Bits，点击阅读原文链接可查看原文。

QQ 讨论小群 598022684 / Discord 群

本周刊文章内容同时也开源在 fe-bits-weekly，欢迎关注。

今天是 2026 年 2 月 8 日，星期天。

虽然发的有点晚，已经 0 点了。

就快要过年放假啦！愉悦地停更俩星期！

这周忙自己的项目很愉悦，给我的博客新增了以前的 shoka 语法兼容和歌单版块，全部可开关。

这周把心心念念的博客歌单和播放器加上了，对我就是故意在写这个语法让你们看看，并且添加了之前 Hexo Shoka 主题的 Markdown 扩展语法兼容支持。

可在这里查看全部新增的语法演示：Shoka 主题 Markdown 语法演示

然后增加音乐播放器和歌单页面，都可以开关～

真的是一点一点变成我想要的样子了～

github.com

Release v2.6.0 · cosZone/astro-koharu

Complete #85 为 astro-koharu 博客添加 Hexo Shoka 主题的 Markdown 扩展语法兼容支持，实现了完整的从 Shoka 主题迁移所需的 Markdown 功能集。可在这里查看全部新增的语法演示：Shoka 主题 Markdown 语法演示刚上线可能还存在很多 bug，欢迎 issue 报告。新增 Markdown 语法文字特效: ++ins+…

https://github.com/cosZone/astro-koharu/releases/tag/v2.6.0

所以……现在我要激情安利山山歌单了!

只要你喜欢山山和中 V 我们就是好朋友！不喜欢也可以是

山山嘿嘿嘿山山……

并且这周给 Moe Copy AI v0.3.5 新增了完整的 Prompt Template 管理功能，支持预设模版和自定义模版。之前还添加了深色模式！（是的没错都是我自用的功能）

moe.cosine.ren

MoeCopy AI - 萌萌哒的 AI 网页数据提取助手

智能识别并提取网页中的结构化数据，为 AI 模型提供高质量输入

https://moe.cosine.ren/docs/changelog

社区动态

GitHub 正在讨论开源项目维护者如何应对日益增加的低质量、AI 生成的拉取请求（PR），可能包括允许用户完全禁用 PR，或者至少限制 PR 只能由协作者访问等操作，可以在这里参加讨论：Exploring Solutions to Tackle Low-Quality Contributions on GitHub
Gatsby v5.16 支持 React 19，Rspress 2.0 重大升级
New to the web platform in January：汇总了 2026 年 1 月 Web 平台的重大进展，包括 Chrome 144 和 Firefox 147 稳定版的发布。其中 CSS 锚点定位 (CSS Anchor Positioning) 和 Navigation API 随着 Firefox 的支持，都正式达到 Baseline Newly Available（新可用基准）状态。此外，Chrome 144 引入了期待已久的 Temporal API、声明式的 <geolocation> 元素以及用于自定义页内搜索样式的 ::search-text 伪元素
互联网档案馆发布插件，解决 40% 的互联网死链问题 - 小众软件：互联网档案馆（Internet Archive）推出了 WordPress 插件 Link Fixer，旨在解决互联网日益严重的“链接腐化”（Link Rot）问题。该插件通过自动检测失效的 URL（如 404 错误），并引导用户访问 Wayback Machine 中存储的历史网页快照，据称能修复约 40% 的死链。

ViteLand 最新消息：2026 年 1 月回顾

voidzero.dev

What’s New in ViteLand: January 2026 Recap

Our January 2026 recap features the unified redesign across VoidZero, Vite, Vitest, Rolldown, and Oxc websites, plus updates across all projects and community highlights.

https://voidzero.dev/posts/whats-new-jan-2026

品牌与设计统一

实现了 VoidZero 旗下所有项目（Vite, Vitest, Rolldown, Oxc）的视觉身份统一，发布了全新的官网和 Logo。
更新了 Vite 的启动模板（Starter Templates），将新品牌标识内置其中。
强调了工具链的深度集成：Vite 8 在底层直接使用 Rolldown 和 Oxc，实现了一致的开发者体验。

核心项目进展

Vite：自 2020 年发布以来，累计下载量超过 30 亿次；React 服务端组件（React Server Components, RSC）插件进行了优化，以支持 TanStack Start 等框架。
Vitest：启动 4.1 测试版（Beta），引入测试标签（Test Tags）功能，并支持通过禁用 viteModuleRunner 选项在脱离 Vite 的情况下运行。
Rolldown：正式达成候选发布版（Release Candidate, RC）里程碑，API 进入稳定阶段；推出“Lazy Barrel Optimization”，在 AntDesign 等场景下可减少 92% 的模块编译，提速 2 倍。
Oxc：Oxlint 支持 oxlint.config.ts 动态配置；Oxfmt 实现了与 Prettier 100% 的一致性（Conformance），并新增了 Tailwind CSS 类名排序功能。

社区动态与生态

榜单表现：在 2025 JavaScript Rising Stars 榜单中，Vite、Oxc、Rolldown 和 tsdown 均名列前茅。
生态迁移：Hugging Face、Turborepo 和 Lichess 等知名项目宣布从 ESLint/Prettier 迁移至 Oxlint/Oxfmt。
周边工具：社区推出了基于 Oxc 的代码体积优化工具 jsshaker 以及 Oxlint 的终端用户界面工具 oxlint-tui。

文章

A Percise Parser：本文介绍了一个因硬编码地区数值格式（Locale Formatting）并使用拙劣的字符串操作，导致国际化失效的 JavaScript 解析器（Parser）案例。
Solving Shrinkwrap: New Experimental Technique
好文，利用 CSS Anchor Positioning（锚点定位）和 Scroll-Driven Animations（滚动驱动动画）解决网页排版中“自动换行导致的容器宽度无法自动收缩（Shrinkwrap）”这一经典难题。
Performance-Optimized Video Embeds with Zero JavaScript：本文介绍了一种利用原生 HTML 标签 <details> 和 <summary> 来优化视频嵌入性能的方法。通过这种方案，开发者可以在完全不使用 JavaScript 的情况下实现视频的按需加载。
CSS @scope: An Alternative To Naming Conventions And Heavy Abstractions：介绍如何利用 CSS 原生的 @scope 规则来替代复杂的 BEM 命名规范或繁重的 CSS 框架，实现更简洁、可维护的样式隔离。
CSS Bar Charts Using Modern Functions | CSS-Tricks：本文介绍了如何利用 CSS 现代函数 sibling-index() 和增强后的 attr() 函数，以更简洁、高效的方式构建纯 CSS 柱状图。

新特性

Nice Select · February 3, 2026：本文展示了如何利用最新的 CSS 特性（如 appearance: base-select）在保持原生无障碍性的同时，打造高度可定制且视觉华丽的 <select> 下拉组件。

CodePen - editor

Pen: pen

Drawing Connections with CSS Anchor Positioning - Roland Franke：锚点定位真好玩儿吧。在无需 JavaScript 的情况下实现 UI 元素（如评论与其回复）之间的视觉连线。

See the Pen gbMxLdL by ROL4ND909 (@ROL4ND909) on CodePen.

工具

jamiepine/voicebox 一款由 Qwen3-TTS 驱动的开源、本地优先语音克隆与合成工具

Codepen 与趣站

不规则网格上带有凹面圆角的卡片

See the Pen WbxpKPQ by thebabydino (@thebabydino) on CodePen.

“卡片和按钮之间的缝隙实现了真正的透明效果。没有尖角，全部都是圆角。除了 .jpg 格式的卡片背景图外，没有其他图片。卡片形状会根据按钮的大小和形状进行调整——您可以尝试只更改按钮元素的字体大小来查看效果。这不需要任何 JavaScript 代码——一切都归功于 CSS 子网格的神奇功能！” by Ana Tudor

带有自定义 select 的文件夹堆叠

See the Pen dPXdgae by captainbrosset (@captainbrosset) on CodePen.

现在选择元素是可以自定义的，Patrick Brosset 向我们展示了点击后会弹出的文件夹堆叠，这给我们带来了很多乐趣。

二进制时钟

See the Pen zxBpPYW by prisoner849 (@prisoner849) on CodePen.

prisoner849 在这段 Three.js 代码中展示了一款精美的时钟。即使你不懂二进制时间，也能欣赏它的美——拿起时钟转动一下，从各个角度欣赏它塑料材质的光泽。

Refs

FE Bits Vol.25 | Yarn 6 将用 Rust 重写，CSS Grid Lanes 进展

Sun, 01 Feb 2026 15:20:36 GMT

本期网址 https://blog.cosine.ren/post/weekly-25
本周刊更新时间期望是在每周天。
推荐订阅本周刊的 RSS。
公众号前端周周谈 FE Bits，点击阅读原文链接可查看原文。
QQ 讨论小群 598022684 / Discord 群
本周刊文章内容同时也开源在 fe-bits-weekly，欢迎关注。

今天是 2026 年 2 月 1 日，星期天。

已经 2 月了啊，好快哦。

个人动态

碎碎念

看了超时空辉夜姬，给我看的好感动……好久没看到这么令人感动的国宴了……

简直是神，还是真百，推荐所有人观看美少女贴贴，在我心里是作画运镜无死角全方面的神作～

撒糖撒糖还是撒糖，后劲也大，全程都在库库截图，我没有什么不满的我觉得美少女特别有活力的贴贴特别好。

上一次看完有如此感慨的还是游戏人生剧场版……但是那个高度……

这部的优缺点都很明显，在强无敌的作画下剧情的平平无奇反而变成了短板，但是我觉得还是瑕不掩瑜，非常非常值得一看！

泛式说得好啊：

https://www.bilibili.com/video/BV1Fcz1BZEVz

bilibili.com

这个杂谈说得也很好：

https://www.bilibili.com/video/BV1w8zrBHEZC

bilibili.com

项目更新

给博客做了以下更新。

github.com

Release v2.5.0 · cosZone/astro-koharu

What’s Changed v2.5.0 by @yusixian in #72 修复了一个 slug 大小写不匹配的 bug，当博客文件用 PascalCase 命名（如 MyPost.md）时，AI 摘要和相关文章推荐会加载失败，改为生成时统一小写 #70 优化 SEO 新增独立的无后端 CMS 管理应用，支持文章管理、浏览器内编辑、Markdown 预览等功能。 #75…

https://github.com/cosZone/astro-koharu/releases/tag/v2.5.0

github.com

Release v2.5.1 · cosZone/astro-koharu

What’s Changed v2.5.1 by @yusixian in #78 Fixes #77 #76 统一时区处理，支持在 config/site.yaml 配置站点时区修复 gray-matter 将 YAML 日期错误解析为 UTC 的问题修复 CMS 前端 JSON.stringify 导致日期时区偏移的问题增强链接预览，为链接预览功能添加图片错误处理机制 Fu…

https://github.com/cosZone/astro-koharu/releases/tag/v2.5.1

给 Moe Copy AI 插件做了深色模式，还在持续优化中。

github.com

Release v0.3.3 · yusixian/moe-copy-ai

文档 | Chrome 商店 | Firefox 附加组件本次更新实现完整的深色模式支持，并对整个设计系统进行了重构。 v0.3.3 by @yusixian in #37 新功能主题选择能力：集成全局 Theme Context，组件统一感知主题使用 Tailwind CSS 插件与集中化主题变量，统一主题管理 UI 组件支持主题感知样式并改进类名管理重构组件样式全面迁…

https://github.com/yusixian/moe-copy-ai/releases/tag/0.3.3

社区动态

When will CSS Grid Lanes arrive? How long until we can use it?：探讨了 CSS Grid Lanes（原生瀑布流布局）在各浏览器的实现进度，并详细介绍了如何通过渐进增强（Progressive Enhancement）技术在当下提前使用这一新特性。
- Safari 已经在技术预览版中支持
- Firefox 在 2020 年最早实现了早期草案，目前正致力于更新至最新的规范语法和 flow-tolerance 属性
- Chrome 与 Edge 的加入：Chromium 团队在经历了语法争议后，目前已达成共识并正在更新其实现代码，标志着三大引擎达成一致。
Yarn 6 预览版发布，为了极致性能正转向使用 Rust 语言重构，预计 2026 年 Q3 发布稳定版。
Try text scaling support in Chrome Canary：介绍 Chrome Canary 中新增的 <meta name="text-scale"> 标签，该功能允许网页响应移动端操作系统的全局字体大小设置。
React 紧急发布 19.2.4、19.1.5 和 19.0.4 版本，修复了 React Server Components (RSC) 中未完全解决的拒绝服务 (DoS) 漏洞：Denial of Service Vulnerabilities in React Server Components (真累啊)
Vercel 的最新研究表明，在针对 Next.js 16 开发的最新评估中，他们发现将 8KB 的文档索引塞进 AGENTS.md 文件中效果更好，因为 skills 无法可靠地触发。
SolidJS 创始人 Ryan Carniato 发布 JavaScript Frameworks - Heading into 2026，分析当前充满活力的前端开发领域。

优质文章

Unstacking CSS Stacking Contexts — Smashing Magazine：非常好的好文章！条理清晰，深入剖析 CSS 层叠上下文 (Stacking Contexts) 的工作原理，解释为什么 z-index 会失效，并提供实用的调试技巧与解决方案。被安利了 Better CSS Stacking Contexts 这个 vscode 插件。
There is No Need to Trap Focus on a Dialog Element：介绍在使用原生 <dialog> 元素时，为什么开发者不再需要手动实现复杂的焦点陷阱（Focus Trap）逻辑。
From pixels to characters: The engineering behind GitHub Copilot CLI’s animated ASCII banner：本文深入探讨了为 GitHub Copilot CLI 开发 3 秒 ASCII 动画背后的复杂工程实现，涵盖了终端渲染限制、色彩一致性及无障碍设计。

10 Tips for Claude Code

Claude Code 的开发者 Boris Cherny 分享了其使用 Anthropic 最新推出的 Claude Code 命令行工具的进阶技巧，涵盖自动化、调试、学习模式及多代理协作。

1. 自动化与技能扩展（Skills & Automation）

建议将每日重复操作转化为自定义技能（Skills），并提交至 Git 仓库供跨项目复用。
创建 /techdebt 指令，在每个会话结束时运行，用于发现并消除重复代码。

2. 高效调试与流程集成（Debugging & CI/CD）

启用 Slack MCP（Model Context Protocol），直接将 Slack 中的 Bug 讨论贴入 Claude 进行修复，减少上下文切换（Context switching）。
授权 Claude 自动修复失败的 CI 测试，或通过分析 Docker 日志定位问题，无需微观管理（Micromanage）。

3. 提示词工程与代码评审（Prompting & Code Review）

让 Claude 扮演评审者（Reviewer），通过“对我提交的代码进行质询，直到通过测试再创建 PR”等提示词提升质量。
要求 Claude 对比主分支（Main branch）和功能分支的行为差异，证明代码的有效性。

4. 环境配置与工具优化（Environment & Setup）

推荐使用 Ghostty 终端以获得更好的同步渲染和 24 位色彩支持。（我用 warp 也很好用）
使用 /statusline 自定义状态栏，实时显示上下文使用情况（Context usage）和当前 Git 分支。

5. 复杂任务与数据分析（Subagents & Analytics）

在请求中加入 “use subagents” 指令，让 Claude 投入更多算力（Compute）处理复杂问题，并保持主代理上下文整洁。
通过编写技能调用 BigQuery (bq) 等命令行工具，直接在 Claude Code 中进行实时数据指标分析。

6. 深度学习与知识内化（Learning & Understanding）

在 /config 中开启“解释模式”（Explanatory/Learning output style），让 Claude 解释代码变更背后的原因（Why）。 (我觉得这个解释模式真的好用)
利用 Claude 生成视觉化的 HTML 演示文稿（Slides）或 ASCII 图表，辅助理解陌生的代码库或协议。
构建间隔重复（Spaced-repetition）学习技能，通过问答形式填补知识盲区。

新特性

如何为新的 ::search-text 和其他高亮伪元素设计样式：介绍 Chrome 144 新推出的 ::search-text 伪元素，以及如何利用 CSS 相对颜色语法统一美化各种文本高亮样式。
告别 insertBefore，使用 moveBefore 移动 DOM 元素介绍了原生 DOM 新 API moveBefore 的用法、优势及其在 Web Components 中的应用，并对比了传统 insertBefore 的局限性。

工具

agentation：一款为 AI Agents 设计的视觉反馈工具，通过点击并添加标注，随后生成包含元素路径、CSS 选择器（Selectors）、位置等详细上下文的 Markdown 文本。文档| Tweet

这个 MarginLab 挺有意思的，一个针对 Claude Code 和 Codex 的独立性能监控工具，模拟真实用户编码场景来监测大模型的“降智”，

趣站与 Codepen 精选

React Tilt Button - 3D Tactile React Button Component

好喜欢这个！感觉是很巧妙的设计。一个具备 3D 触感、支持倾斜和深度效果的 React 交互按钮组件。它利用 CSS 的 3D 变换（3D Transforms）技术，为传统的按钮元素注入了物理深度（Depth）和动态倾斜（Tilt）效果。组件不仅内置了从复古游戏（Arcade）到现代金属（Steel）等多种预设主题，还开放了高度细粒度的自定义参数，让开发者可以轻松调整按钮的海拔高度（Elevation）、圆角（Radius）及光泽感（Glare），从而打造出极具表现力的用户界面。

react-tilt-button.vercel.app

React Tilt Button - 3D Tactile React Button Component

A beautiful 3D tactile React button with squishy press, hover tilt, depth and smooth interactions. Perfect for modern UI and landing pages.

https://react-tilt-button.vercel.app/

GitHub 源码

github.com

GitHub - archisvaze/react-tilt-button: A tactile 3D button for React that tilts on hover and squishes on press. Modern and dependency-free.

A tactile 3D button for React that tilts on hover and squishes on press. Modern and dependency-free. - archisvaze/react-tilt-button

https://github.com/archisvaze/react-tilt-button

Super Monkey Ball

开发商 Twilight 将世嘉经典游戏《超级猴子球》移植到网页上，做得非常出色且运行流畅。

bsky.app

Twilight (@twilightpb.bsky.social)

I ported Super Monkey Ball to a website. You can access it in the replies. (or just type what you see in the video, I’m not your boss.)

https://bsky.app/profile/twilightpb.bsky.social/post/3mdbynphtbc2l

monkeyball-online.pages.dev

SMB1 Web Gameplay

https://monkeyball-online.pages.dev/

可以查看源代码。

Typewriter Web Component V2

See the Pen EaKjXwB by luis-lessrain (@luis-lessrain) on CodePen.

目前该项目仅在 CodePen 上提供，但它的效果非常出色。演示允许您交互式地启动、暂停/恢复、完成和重置动画。此外，还有一个进度条和按钮，可以跳转到特定的进度点。

Refs

FE Bits Vol.24 | Rolldown 1.0 RC、Anime.js v4.3 自动布局与 Chrome 145 100vw 滚动条感知

Sun, 25 Jan 2026 10:53:00 GMT

本期网址 https://blog.cosine.ren/post/weekly-24
本周刊更新时间期望是在每周天。
推荐订阅本周刊的 RSS。
公众号前端周周谈 FE Bits，点击阅读原文链接可查看原文。
QQ 讨论小群 598022684 / Discord 群
本周刊文章内容同时也开源在 fe-bits-weekly，欢迎关注。

今天是 2026 年 1 月 25 日，星期天。

个人动态

碎碎念

以下是一些碎碎念杂谈：

越用 AI 会越有种「啊他果然取代不了我」的感觉，尤其是他犯蠢的时候。

但是很多时候又很方便确确实实省下来了很多摸鱼时间，又爱又恨的感觉。

也不奇怪很多程序员会排斥 AI 写代码，因为架构上真的很容易犯蠢，写的代码但凡是个代码洁癖都会感觉哎呦还不如自己来写，但是重复性业务工作真的太省劲了。

虽然下沉市场和资本感觉都在 AI 狂欢，但我体感上的话，感觉其实平常程序员的生活是从写代码变成审计划和审代码改代码了，更爽了，写自己的东西更有劲了 x

ai 真的容易堆屎山，我现在每次写完让 opus 4.5 review 一遍 codex review 一遍都差不多了我再看才能好点儿，不过他们自己 review 的效果还是挺好的。

PS: 仅限前端/ Swift 领域，后端我只能通过同事的使用感受推测。

项目更新

github.com

GitHub - yusixian/moe-copy-ai: ✨ 萌萌哒的 AI 网页数据提取助手 ✨

✨ 萌萌哒的 AI 网页数据提取助手 ✨. Contribute to yusixian/moe-copy-ai development by creating an account on GitHub.

https://github.com/yusixian/moe-copy-ai

我很喜欢现在 Moe Copy AI 的内容提取功能～

现在可以直接选中提取推文串进行总结的，准备下个版本改改加一下常用的选择器，现在还是直接选中元素提取出来进行总结。

然后这周 Moe Copy AI 发了 v0.3.0，太感动了终于有大佬 @hakadao 帮忙改了一下最开始 AI 写的一坨的 UI 了，工作量巨大，现在 UI 清爽多了！（#26）

虽然现在还在陆续改，但是我也看不下去之前的了所以直接推了一版（

更新日志 | 下载

博客更新

然后博客更新这边，最近把我们的 Electron 应用配置上了 Mac 端的 TestFlight，用 GitHub Actions 实现自动化构建和上传。踩了不少坑，记录一下整个流程。

用 GitHub Actions 自动化 Electron 上架 MAS（Mac App Store）

然后给 astro-koharu 添加了无后端的编辑功能，只在本地 dev 模式有，还打算加一个无后端管理本地文章的 CMS 功能，灵感来源于上周发的 OS 即 CMS 文章
编辑器使用的是 BlockNote 是好用的，基于 Prosemirror 和 Tiptap。

另外现在可以自动创建不存在的分类映射了，也可以改～

社区动态

Announcing Rolldown 1.0 RC：Rolldown 正式发布 1.0 发布候选版本（RC），作为 Vite 未来的核心打包工具，它在保持 Rollup 兼容性的同时，凭借 Rust 实现了 10-30 倍的速度提升。此 RC 标志着 API 的稳定性。在 1.0 之前不会有任何破坏性改动。
Vercel 公布了 skills.sh，是一个用于查找和共享代理 Skills 的网站，其中 Remotion 也出了 skill，现在只需要使用 Claude Code 即可通过编程方式制作视频！通过 npx skills add remotion-dev/skills。

Using 100vw is now scrollbar-aware：从 Chrome 145 开始，如果根元素（而非 body ）设置了overflow: scroll，则在 vw 的大小中应考虑默认滚动条宽度，解决了长期以来因视口单位导致的网页多余水平滚动问题。该改进同样适用于 vh（对应水平滚动条）以及视口单位的小、大、动态变体（sv*, lv*, dv*）

Anime.js v4.3

Anime.js v4.3 发布，引入强大的自动布局（Auto Layout）动画功能，支持平滑处理复杂的 CSS 布局变换。

这个真的好诶！跨框架造福前端人。

官方提供了文档说明和发布日志，并在 CodePen 上发布了示例集合

找了一个示例如下，太丝滑了：

See the Pen PwzmxwR by juliangarnier (@juliangarnier) on CodePen.

优质文章

不会编程的人能靠 AI 独立开发应用吗？：作者认为，AI 确实大幅降低了“将想法翻译成代码”的技术门槛，但“不会编程”、“靠 AI”和“应用”这些词语的边界远比想象中模糊。在与 AI 协作的过程中，使用者会不自觉地习得编程概念，AI 更多是作为博学但死板的“徒弟”或“翻译官”，帮助有逻辑、有想法的人实现愿景，而非代替思考和定义问题。
Inside Turbopack: Building Faster by Building Less：深入解析 Next.js 的新一代打包工具 Turbopack 如何通过增量计算（Incremental Computation）和细粒度缓存实现极致的开发响应速度。
The Incredible Overcomplexity of the Shadcn Radio Button：探讨了现代前端 UI 框架（如 Shadcn）如何将原本简单的原生单选按钮变得异常复杂，并呼吁回归 CSS 原生开发。
HTTP Archive 2025 Web Almanac | CSS-Tricks：介绍 HTTP Archive 发布的 2025 年度《Web 年鉴》报告，总结了当前 Web 性能、CSS 趋势、可访问性及资源膨胀等核心数据。
The challenges of soft delete：探讨了传统“软删除”模式（如 archived_at 列）带来的长期复杂性，并对比分析了触发器、应用层事件和 WAL 等更优的替代方案。
对于新项目，作者优先推荐基于触发器的方案，因为它部署简单、不引入额外基建，且有效隔离了活跃数据与归档数据。
Rethinking “Pixel Perfect” Web Design — Smashing Magazine：探讨了在多设备、响应式和动态内容的现代 Web 环境下，为何传统的“像素级完美（Pixel Perfect）”观念已不再适用。
localspace：现代化的 localForage 替代方案，提供简单的浏览器存储封装。
Overscroll Effects On Nested Scrollers In All Browsers：Chrome 145 现已支持嵌套滚动容器的过度滚动效果（Overscroll Effects），实现了全浏览器体验的一致性。此前该效果仅在根页面有效，且只有 Safari 和 Firefox 支持子容器的回弹。
How to animate SVG with CSS: Tutorial with examples：这篇教程详细介绍了如何利用 CSS 属性和关键帧动画为 SVG（Scalable Vector Graphics，可缩放矢量图形）添加动态效果，从基础嵌入到复杂的路径动画均有涵盖。

新特性

Follow-the-leader pattern with CSS anchor positioning：介绍如何利用 CSS 锚点定位（CSS Anchor Positioning）实现元素跟随交互目标移动的“随动”（Follow-the-leader）模式。

工具

darula-hpp/shimmer-from-structure：一个能够根据 React 组件实际 DOM 结构自动生成像素级精确骨架屏（Shimmer Skeleton）的工具库。
Better SVG：用于编辑带有实时预览功能的 SVG 文件的 VS Code 扩展程序，包含许多实用功能，例如实时预览、颜色选择器、缩放/平移控件、可编辑的配色方案 currentColor 值、深色背景切换以及 SVGO 集成，一键优化 svg 体积。

趣站与 Codepen 精选

使用 CSS 中的 drop-shadow() 滤镜为不规则形状添加阴影

wad-platform-prod.pages.dev

Adding shadows to irregular shapes in CSS with filter: drop-shadow()

Using box-shadow you can add shadows to any rectangular HTML element. But you can also use filter: drop-shadow() to add shadows to irregular shaped images.

https://www.wearedevelopers.com/en/magazine/675/adding-shadows-to-irregular-shapes-in-css-with-filter-drop-shadow-675

Chris Heilmann 向我们展示了如何使用 filter: drop-shadow() 为不规则形状添加阴影，该过滤器可以识别“图像的透明部分或 SVG 路径的形状，并相应地应用阴影”。

See the Pen qENbVmb by codepo8 (@codepo8) on CodePen.

使用 superellipse() 函数创建迷人的角形 — 仅 CSS

在这个由 Zoran Jambor 创作的 Pen 中，一个简单的圆形通过“ superellipse() CSS 函数的随机值”演变成万花筒般的形状。点击“关于”按钮，即可查看关于 superellipse() 函数的简短教程和实用资源。

See the Pen ogLLLgr by ZoranJambor (@ZoranJambor) on CodePen.

CSS 光学错觉

Alvaro Montoro 在这份令人惊艳的合集中分享了大量用纯 CSS 实现的著名光学错觉作品。其中一张在电视模式下简直太震撼了 ‍

https://codepen.io/collection/GpWqKk

codepen.io

旧布随风飘扬

在 Sabo Sugi 的这个 Three.js 场景中，一块饱经风霜的布料在微风中轻轻飘动。深入设置控件，即可更改图像、颜色、风力和撕裂效果。

See the Pen ByzLYpb by sabosugi (@sabosugi) on CodePen.

Refs

用 GitHub Actions 自动化 Electron 上架 MAS（Mac App Store）

Fri, 23 Jan 2026 15:02:00 GMT

最近把我们的 Electron 桌面应用配置上了 Mac 端的 TestFlight，用 GitHub Actions 实现了自动化构建和上传。踩了不少坑，记录一下整个流程。

我对 Electron 和 MAS 上架流程也不熟悉，这篇文章是一点点摸索出来的。目前已经能够成功上传到 TestFlight，但如有错漏请务必帮忙指出！部分记录是通过和 AI 对话的方式存留下来的，可能有错漏。

⚠️ 时间成本警告：整个 workflow 会消耗大量 GitHub Actions 免费额度！苹果的代码签名和公证（notarization）过程需要硬等 3～5 分钟，这段时间 runner 只能空转等待苹果服务器响应，非常不划算。如果你的项目频繁构建，建议考虑自建 runner 或优化触发策略。

这是苹果官方的文档 Upload builds，介绍了如何使用 Apple 官方工具及 API 将 App 构建版本上传至 App Store Connect 的指南。

先放最终的效果，为什么会有这么麻烦的东西啊（小声抱怨）：

配置完成后：

手动触发 workflow
勾选 “Upload to App Store Connect” 则上传到 TestFlight，否则仅打包
在 App Store Connect 的 TestFlight 标签页查看构建
分发给测试人员

整个流程从 DMG 直接下载迁移到 TestFlight 大概花了半天时间，主要是在各种证书和 Bundle ID 配置上踩坑。

根据文档里 Apple 的推荐上传方式如下：

Xcode：苹果官方集成开发环境（IDE），支持从开发、测试到提交的全流程管理
Transporter：提供图形界面的 macOS 应用，适合简单快速地上传并查看交付日志和历史
xcrun altool：通过 Xcode 自带的 xcrun 来调用 altool，这是命令行工具，可用于验证应用二进制文件并将其上传到 App Store Connect
App Store Connect API：基于 REST 的 API，支持通过 JSON Web Tokens (JWT) 进行身份验证，实现自动化上传流程

因为我们要使用 action，所以这里我们使用 xcrun altool 进行上传

背景

我们的应用是用 Electron + React + TypeScript 构建的，之前通过 GitHub Releases 分发 DMG 安装包。现在想通过 TestFlight 进行 beta 测试，最终上架 Mac App Store。以下步骤假设你的 app 名称为 AppCat。

前置条件：在 App Store Connect 创建应用

在开始配置证书之前，需要在 App Store Connect 创建应用：

打开 App Store Connect - 我的 App
点击 ”+” → 新建 App
平台勾选 macOS
名称填写应用名
Bundle ID 选择或创建一个（必须和 electron-builder.yml 中的 appId 完全一致！）
SKU 随便填，如 appcat-macos

⚠️ 如果跳过这一步，后面上传时会报错 “No suitable application records were found”。

我们的应用之前上架过 iOS，所以这里就不赘述了，就是常规的上架流程，现在是要上架 Mac 端的 App Store。

两种分发方式的区别

首先要理解，Mac 应用有两种分发方式，它们需要不同的证书：

分发方式	证书类型	用途
直接下载 (DMG)	Developer ID Application	网站/GitHub 下载安装
Mac App Store	3rd Party Mac Developer Application	App Store / TestFlight

另外，MAS 版本强制要求沙盒，这意味着一些功能（如 desktopCapturer 屏幕截图）可能受限。

第一步：创建证书

1.1 创建 CSR 文件

打开本地的钥匙串访问：

顶部菜单栏 → 钥匙串访问 → 证书助理 → 从证书颁发机构请求证书...

然后填写：

用户电子邮件地址：你的邮箱
常用名称：随便填，如 “AppCat MAS”
选择”存储到磁盘”
CA 邮件地址：留空

保存 .certSigningRequest 文件。

1.2 创建 Mac App Distribution 证书

打开 Apple Developer - Certificates
点击 ”+” 按钮
选择 Mac App Distribution
上传刚才的 CSR 文件
下载证书，双击安装到钥匙串（选择”登录”钥匙串）

1.3 创建 Mac Installer Distribution 证书

重复上面的步骤，但选择 Mac Installer Distribution。这个证书用于签名 .pkg 安装包。

第二步：创建 Provisioning Profile

打开 Apple Developer - Profiles
点击 ”+”
选择 Mac App Store Connect
选择你的 App ID（必须和 App Store Connect 中的 Bundle ID 一致！）
选择刚创建的 Mac App Distribution 证书
命名并下载

⚠️ 重要：Profile 中的 Bundle ID 必须和 App Store Connect 中的完全一致，否则上传会报错 “No suitable application records were found”。

这一步得到 appcat_profile_mas.provisionprofile 文件（文件名可自定义，但要和后续配置保持一致）。

第三步：创建 App Store Connect API Key

用于 CI/CD 自动上传构建。

打开 App Store Connect - 用户和访问 - 密钥
点击 ”+” 创建新密钥
名称随便填，权限选 App 管理 或 管理员
点击 “生成”

找到 Issuer ID

Issuer ID 显示在密钥页面的顶部，是一个 UUID 格式的字符串，例如：

50ce4b17-dd5e-4550-877b-7a7bb0d608d7

所有属于同一团队的 API Key 共享同一个 Issuer ID，这个值不是敏感信息。

获取 Key ID

创建密钥后，Key ID 会显示在密钥列表中（密钥 ID 列），例如 BU64538829。

下载 .p8 私钥文件

点击 “下载 API 密钥” 下载 .p8 文件：

文件名格式为 AuthKey_XXXXX.p8，其中 XXXXX 是 Key ID
这个文件是 API 认证的私钥，泄露会导致安全问题

⚠️ 极其重要：.p8 私钥文件整个团队只能下载一次！下载后立即保存到安全位置（如密码管理器）。如果丢失，只能撤销当前密钥并重新创建，届时需要更新所有使用该密钥的 CI/CD 配置。

这一步得到三个值：

AuthKey_XXXXX.p8 文件 → 后面转为 ASC_API_KEY
Key ID → 对应后续我们在环境变量设置的 ASC_API_KEY_ID
Issuer ID → 对应 ASC_ISSUER_ID

第四步：导出证书为 .p12

CI/CD 需要 .p12 格式的证书。

打开钥匙串访问
左侧选择”登录”，上方选择”我的证书”
找到 “3rd Party Mac Developer Application: xxx”
- 右键 → 导出
- 格式选 .p12
- 设置密码
同样导出 “3rd Party Mac Developer Installer: xxx”

这一步得到了 mas_app.p12 和 mas_installer.p12 文件。

第五步：electron-builder 配置

在 electron-builder.yml 中添加 MAS 配置：

appId: app.bundlename.AppCat # 必须和 App Store Connect 一致！这里替换为你的 app bundleId

# 现有的 Developer ID 配置保持不变
mac:
  entitlementsInherit: build/entitlements.mac.plist
  hardenedRuntime: true
  notarize: true

# 新增 Mac App Store 配置
mas:
  hardenedRuntime: false # MAS 用沙盒代替
  entitlements: build/entitlements.mas.plist
  entitlementsInherit: build/entitlements.mas.inherit.plist
  provisioningProfile: build/appcat_profile_mas.provisionprofile
  notarize: false # MAS 不需要 notarize
  category: public.app-category.productivity # 这里选择你的应用分类

# PKG 配置
pkg:
  isRelocatable: false
  overwriteAction: upgrade
  artifactName: ${name}-${version}-mas.${ext}

第六步：创建 MAS Entitlements

MAS 必须启用沙盒。创建 build/entitlements.mas.plist：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>com.apple.security.app-sandbox</key>
    <true/>
    <key>com.apple.security.network.client</key>
    <true/>
    <key>com.apple.security.files.user-selected.read-write</key>
    <true/>
    <key>com.apple.security.files.downloads.read-write</key>
    <true/>
  </dict>
</plist>

创建 build/entitlements.mas.inherit.plist（子进程继承）：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>com.apple.security.app-sandbox</key>
    <true/>
    <key>com.apple.security.inherit</key>
    <true/>
  </dict>
</plist>

第七步：配置 GitHub Secrets

在 GitHub 仓库的 Settings → Environments 中创建 staging 环境，添加以下 Secrets：

# 转换文件为 base64
base64 -i mas_app.p12 | pbcopy        # → MAS_APP_CERT
base64 -i mas_installer.p12 | pbcopy  # → MAS_INSTALLER_CERT
base64 -i appcat_profile_mas.provisionprofile | pbcopy  # → MAS_PROVISIONING_PROFILE
base64 -i AuthKey_XXXXX.p8 | pbcopy   # → ASC_API_KEY

Secret	描述
`MAS_APP_CERT`	Mac App Distribution 证书 (base64)
`MAS_INSTALLER_CERT`	Mac Installer Distribution 证书 (base64)
`MAC_CERTS_PASSWORD`	证书密码
`MAS_PROVISIONING_PROFILE`	Provisioning Profile (base64)
`ASC_API_KEY`	App Store Connect API 私钥 (base64)
`ASC_API_KEY_ID`	API Key ID
`ASC_ISSUER_ID`	Issuer ID

第八步：GitHub Actions Workflow

创建 .github/workflows/release-mas.yml：

这里其实我创建了自己的 self-host action runner 试了试，就没去掉，可以忽略，默认行为是用 GitHub 的 runner。

name: Build and Release MAS

on:
  workflow_dispatch:
    inputs:
      upload_to_app_store:
        description: "Upload to App Store Connect"
        type: boolean
        default: false
      use_self_hosted_runner:
        description: "Use self-hosted runner"
        type: boolean
        default: false

jobs:
  build-mas:
    runs-on: ${{ inputs.use_self_hosted_runner && fromJSON('["self-hosted", "macOS", "ARM64"]') || 'macos-14' }}
    environment: staging
    permissions:
      contents: write

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Setup pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 9

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Import Mac App Store Certificates
        uses: apple-actions/import-codesign-certs@v3
        with:
          p12-file-base64: ${{ secrets.MAS_APP_CERT }}
          p12-password: ${{ secrets.MAC_CERTS_PASSWORD }}
          keychain-password: ${{ secrets.MAC_CERTS_PASSWORD }}

      - name: Import Mac Installer Certificate
        uses: apple-actions/import-codesign-certs@v3
        with:
          p12-file-base64: ${{ secrets.MAS_INSTALLER_CERT }}
          p12-password: ${{ secrets.MAC_CERTS_PASSWORD }}
          create-keychain: false
          keychain-password: ${{ secrets.MAC_CERTS_PASSWORD }}

      - name: Download Provisioning Profile
        run: |
          echo "${{ secrets.MAS_PROVISIONING_PROFILE }}" | base64 -d > build/appcat_profile_mas.provisionprofile

      - name: Build MAS App
        run: MAS_BUILD=true pnpm exec electron-vite build && pnpm exec electron-builder --mac mas --publish never
        env:
          # 你的 env 环境变量等
          VITE_API_BASE_URL: ${{ vars.VITE_API_BASE_URL }}

      - name: Upload to App Store Connect
        if: ${{ inputs.upload_to_app_store }}
        run: |
          # Setup API Key file
          mkdir -p ~/.private_keys
          echo "${{ secrets.ASC_API_KEY }}" | base64 -d > ~/.private_keys/AuthKey_${{ secrets.ASC_API_KEY_ID }}.p8

          # Find and upload the pkg file
          PKG_FILE=$(find dist -name "*.pkg" -type f | head -1)
          echo "Uploading: $PKG_FILE"

          xcrun altool --upload-app \
            --type macos \
            --file "$PKG_FILE" \
            --apiKey ${{ secrets.ASC_API_KEY_ID }} \
            --apiIssuer ${{ secrets.ASC_ISSUER_ID }}

      - name: Upload Build Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: mas-build
          path: |
            dist/*.pkg
          retention-days: 14

踩坑记录

证书导入密码问题

第二次导入证书时必须指定 keychain-password，而且要和第一次创建 keychain 时的密码一致：

# 第一次导入，创建 keychain
- uses: apple-actions/import-codesign-certs@v3
  with:
    keychain-password: ${{ secrets.MAC_CERTS_PASSWORD }} # 必须指定！

# 第二次导入，复用 keychain
- uses: apple-actions/import-codesign-certs@v3
  with:
    create-keychain: false
    keychain-password: ${{ secrets.MAC_CERTS_PASSWORD }} # 必须一致！

No suitable application records 错误

这个错误可能有多种原因：

原因 1：Bundle ID 不匹配

必须确保这三个地方的 Bundle ID 完全一致：

electron-builder.yml 中的 appId
App Store Connect 中的 Bundle ID
Provisioning Profile 绑定的 App ID

查看 Profile 绑定的 Bundle ID：

security cms -D -i appcat_profile_mas.provisionprofile | grep -A1 "application-identifier"

原因 2：API Key 权限不够

创建 API Key 时必须选择 App 管理 (App Manager) 或 管理员 (Admin) 权限。

原因 3：App Store Connect 没有 macOS 应用

确保在 App Store Connect 中已创建应用，且平台包含 macOS。

GH_TOKEN 报错

MAS 构建不需要发布到 GitHub，添加 --publish never：

electron-builder --mac mas --publish never

缺少高分辨率图标

App Store 要求 1024x1024 的图标（512pt @2x）。确保 .icns 文件包含这个尺寸。

API Key 必须写入文件

xcrun altool 需要从文件读取 .p8 私钥，不能直接传入 base64 字符串。在 CI 中需要先解码到指定目录：

- name: Upload to App Store Connect
  run: |
    # altool 会在这个目录查找私钥文件
    mkdir -p ~/.private_keys
    echo "${{ secrets.ASC_API_KEY }}" | base64 -d > ~/.private_keys/AuthKey_${{ secrets.ASC_API_KEY_ID }}.p8

    xcrun altool --upload-app \
      --apiKey ${{ secrets.ASC_API_KEY_ID }} \
      --apiIssuer ${{ secrets.ASC_ISSUER_ID }} \
      ...

PKG 文件路径问题

xcrun altool --file dist/*.pkg 可能会报错 “file cannot be found”，原因：

无匹配文件时：bash 默认会把 dist/*.pkg 当作字面字符串传递
多文件匹配时：所有匹配的文件都会作为参数传递，但 --file 只接受一个

用 find 命令显式获取文件路径更可靠：

PKG_FILE=$(find dist -name "*.pkg" -type f | head -1)
xcrun altool --upload-app --file "$PKG_FILE" ...

希望这篇指南能帮你少走弯路。

再次提醒：这个 workflow 会消耗大量 GitHub Actions 免费额度，苹果的公证过程硬等 3～5 分钟，runner 只能空转。如果你的团队频繁构建，强烈建议自建 runner 或者优化触发策略（比如只在打 tag 时触发）。

FE Bits Vol.23 | jQuery 4 发布，Chrome 新增垂直标签页功能，Astro 被 Cloudflare 收购

Sun, 18 Jan 2026 13:50:00 GMT

本期网址 https://blog.cosine.ren/post/weekly-23
本周刊更新时间期望是在每周天。
推荐订阅本周刊的 RSS。
公众号前端周周谈 FE Bits，点击阅读原文链接可查看原文。
QQ 讨论小群 598022684 / Discord 群
本周刊文章内容同时也开源在 fe-bits-weekly，欢迎关注。

今天是 2026 年 1 月 18 日，星期天。

Moe Copy AI 发了 v0.2.1 和 v0.2.2，做了国际化，将悬浮球的功能抽取至侧边栏单页抓取 tab 了，内容提取下也加了 AI 总结按钮。

感谢 @XueHua-s 贡献的 htmlToMarkdown 重构为使用 unifined 改进～（#19）

然后是 astro-koharu 主题，将周刊功能泛化为了多系列，featuredSeries 支持数组与自定义 slug，动态生成系列页面并替代固定 /weekly 了，现在可以新增以下如图所示的系列文章了。

并且评论组件现在支持切换三种评论组件了（waline / remark42 / giscus）

开心！Waline 做评论真是又好看又好用啊

这周都在肝项目，所以周刊短短的！

社区动态

jQuery 4.0.0：时隔近十年，jQuery 发布了 4.0.0 正式版，带来了大量现代化改进，包括移除对旧版浏览器（IE 10 及更早版本）的支持、引入新特性以及优化内部实现。
Chrome 145 adds Experimental Support for Vertical Tabs：Chrome 145 实验性支持垂直标签页。（天呐 2026 了 Chrome 终于把垂直标签页学过来了太感动了）
隆重推出：React 最佳实践：Vercel 团队将 “十余年 React 和 Next.js 优化经验” 提炼成了一套 Markdown 文件，旨在供 Claude Code 等代码助手使用，当然您也可以自行阅读。其目标是帮助这些助手编写更优质的 React 代码，而无需过多指导。
- 可以通过 npx add-skill vercel-labs/agent-skills 直接安装
The Astro Technology Company joins Cloudflare | Astro：Astro 框架背后的公司 The Astro Technology Company 宣布加入 Cloudflare，以获取更多资源并专注于框架核心开发，承诺保持开源和平台中立。（真好，我很喜欢 astro 写网站的感觉）
- 并且 Astro 回顾了过去一年，展望了 2025 年的更新、变化和新增功能吗，并且发布了 Astro 6 的 beta 版本。
“You should never build a CMS” | Sanity：Sanity 回应 Cursor 将 CMS 迁移至 Markdown 的热议，分享了许多使用 CMS 的理由。

文章与社区动态

Why I hate WebKit, a (non) love letter：非常好文章推一下，Tauri WebKit 坑点大全，珍爱生命远离 WebKit！这个标题和 url 真是直抒胸臆。
JavaScript 的 for-of 循环实际上很快 (V8)：探讨现代 V8 引擎中 for-of 循环的性能表现，打破了开发者社区中关于其性能显著弱于传统循环的固有印象。作者建议现在除非是处理极端海量数据且对每一毫秒都敏感的场景，否则应优先使用语义更佳的 for-of 循环。
GUIDs - How I messed up my RSS feed：这篇文章讲述了作者如何因在 RSS feed 中添加 UTM 参数导致所有文章被重复添加，并介绍了 GUID 字段来解决此类问题的经验。
记 LobeHub 的性能和 DX 优化：作者分享了入职 LobeHub 一个月以来在性能和开发体验（DX）方面进行的优化工作。
《简明 TypeScript 手册》是一本简短精炼的 TypeScript 指南，免费开放阅读。
How to Steal Any React Component 网页做的还挺有趣的，介绍如何使用 React 的内部数据结构（通过 Fiber）和 LLM 来重建生产 React 应用程序中的组件，而无需原始源代码。
How Markdown took over the world：回顾 Markdown 的诞生历程及其如何从一个小众博客工具演变为统治现代互联网和 AI 交互的通用文本标准。
Death to Scroll Fade! 批判网页设计中过度使用“滚动渐入”（Scroll Fade）效果的弊端，呼吁回归简洁高效的用户体验。
useOptimistic Won’t Save You：深入探讨 React 19 的 useOptimistic 钩子，说明其必须结合 Transition 和 Action 状态管理才能真正处理复杂的竞态条件。作者最后建议，这些复杂的底层 API 更多是为框架开发者设计的，普通开发者应倾向于使用成熟框架提供的抽象。
如何衡量和优化 React 性能：全面介绍了衡量和优化 React 应用性能的工具与技术，重点讲解了 React 19.2 的新特性以及各类运行时和构建时的优化策略。
停止将所有内容都变成数组（并减少工作量）：介绍如何利用 JavaScript 原生的迭代器辅助函数（Iterator helpers）实现延迟计算，从而优化处理大数据集时的性能和内存占用。

新特性

Bytes I can delete after all this time 由于 CSS 和 JS 的进步，越来越多的技术我们不再需要了，Remy Sharp 分享了一份我们可以抛弃的技术清单。

CSS 布局与样式增强
- 使用 text-underline-offset 属性轻松控制文本下划线的距离，无需再用复杂的伪元素模拟。
- 在 Flexbox 布局中直接使用 gap 属性，告别过去需要通过处理 margin (外边距) 来设置间距的繁琐操作。
- 采用原生 CSS 嵌套 (Nesting) 和在选择器内嵌套媒体查询 (Media Queries)，使样式结构更清晰且无需预处理器。
- 利用 clamp(min, variable, max) 实现流体响应式尺寸，简化了复杂的断点计算。
- 使用 content: open-quote 结合 q 标签实现根据语言自动适配的本地化引号。
JavaScript 语法与交互优化
- 采用可选的 catch 绑定 (Optional catch binding)，在不需要错误对象时直接写 catch，避免定义未使用的变量。
- 指针事件 (Pointer Events) 的普及使得开发者可以用一套逻辑替代旧有的 click (点击) 和 touch (触摸) 事件的混合逻辑。
- 弃用旧的性能黑科技，如使用 ~~ 或 | 0 取整，现代引擎下 Math.floor() 的可读性更高且性能不再是瓶颈。
资源优化与现代格式
- AVIF 图像格式已获得全面支持，相比 JPEG 可轻松实现 50% 以上的体积缩减。
- 提供了使用命令行工具 avifenc 批量转换图片的实用脚本示例。

然后是两篇锚点定位，都是自动连线：

Connecting Circles With Anchor Positioning II：CSS Tips 锚点定位系列文章，通过改进之前的实现，展示了如何使用 CSS 锚点定位技术动态连接两个圆圈，并在连接箭头的形状中计算并显示它们之间的距离。
纯 CSS 实现两个元素之间折线自动相连：本文详细介绍了如何利用 CSS 锚点定位实现两个元素之间纯 CSS 自动连接的折线效果，并探讨了当前方案的实现原理及局限性。

趣站与 Codepen 精选

Playing With CodePen slideVars：介绍 CodePen 官方推出的 slideVars 工具，它可以自动检测 CSS 变量并生成交互式控制面板，现在在 codepen 里写交互式 Demo 更方便了。

See the Pen myEOqJg by geoffgraham (@geoffgraham) on CodePen.

Refs

Fork 主题如何更新？基于 Ink 构建主题更新 CLI 工具

Mon, 12 Jan 2026 12:30:00 GMT

本文图表、伪代码等由 AI 辅助编写

背景

当你 fork 了一个开源项目作为自己的博客主题，如何优雅地从上游仓库同步更新？手动敲一串 Git 命令既繁琐又容易出错；但直接点 Fork 的 Sync 按钮，又可能覆盖你的自定义配置和内容。

很多人因此在「保持更新」和「保留修改」之间左右为难：要么干脆二开后不再同步，要么每次更新都提心吊胆。

这也是为什么不少项目会像 @fumadocs/cli 一样，提供专门的 CLI 来完成更新等相关操作。

本文将介绍如何简单地构建一个交互式 CLI 工具，把 fork 同步的流程自动化起来。

这个工具的核心目标是：

安全：更新前检查工作区状态，必要时可备份
透明：预览所有变更，让用户决定是否更新
友好：出现冲突时给出明确指引

具体的代码可以看这个 PR：

github.com

Build/backup by yusixian · Pull Request #43 · cosZone/astro-koharu

Summary 新增 Koharu CLI 交互式命令行工具，提供博客内容备份/还原、主题更新、内容生成、备份管理等功能优化类型定义和组件逻辑更新文档以反映新的 CLI 工具使用方式主要改进 Koharu CLI 基于 Ink 构建的交互式 TUI 工具： pnpm koharu # 交互式主菜单 pnpm koharu backup # 备份博客内容 (--full 完整备份)…

https://github.com/cosZone/astro-koharu/pull/43

不过这个 PR 只是最初的版本，后面又缝缝补补了不少东西，整体流程是我研究一个周末后摸索出的，如有不足，那一定是我考虑不周，欢迎指出～

在这个 PR 里，我基于 Ink 构建了一个交互式 TUI 工具，提供了博客内容备份/还原、主题更新、内容生成、备份管理等功能：

pnpm koharu # 交互式主菜单
pnpm koharu backup # 备份博客内容 (--full 完整备份)
pnpm koharu restore # 还原备份 (--latest, --dry-run, --force)
pnpm koharu update # 从上游同步更新 (--check, --skip-backup, --force)
pnpm koharu generate # 生成内容资产 (LQIP, 相似度, AI 摘要)
pnpm koharu clean # 清理旧备份 (--keep N)
pnpm koharu list # 查看所有备份

其中备份功能可以：

基础备份：博客文章、配置、头像、.env
完整备份：包含所有图片和生成的资产文件
自动生成 manifest.json 记录主题版本与备份元信息（时间等）

还原功能可以：

交互式选择备份文件
支持 --dry-run 预览模式
显示备份类型、版本、时间等元信息

主题更新功能可以：

自动配置 upstream remote 指向原始仓库
预览待合并的提交列表（显示 hash、message、时间）
更新前可选备份，支持冲突检测与处理
合并成功后自动安装依赖
支持 --check 仅检查更新、--force 跳过工作区检查

整体架构

infographic sequence-snake-steps-underline-text
data
  title Git Update 命令流程
  desc 从 upstream 同步更新的完整工作流
  items
    - label 检查状态
      desc 验证当前分支和工作区状态
      icon mdi/source-branch-check
    - label 配置远程
      desc 确保 upstream remote 已配置
      icon mdi/source-repository
    - label 获取更新
      desc 从 upstream 拉取最新提交
      icon mdi/cloud-download
    - label 预览变更
      desc 显示待合并的提交列表
      icon mdi/file-find
    - label 确认备份
      desc 可选：备份当前内容
      icon mdi/backup-restore
    - label 执行合并
      desc 合并 upstream 分支到本地
      icon mdi/merge
    - label 处理结果
      desc 成功则安装依赖，冲突则提示解决
      icon mdi/check-circle

更新相关 Git 命令详解

1. 检查当前分支

git rev-parse --abbrev-ref HEAD

作用：获取当前所在分支的名称。

参数解析：

rev-parse：解析 Git 引用
--abbrev-ref：输出简短的引用名称（如 main），而不是完整的 SHA

使用场景：确保用户在正确的分支（如 main）上执行更新，避免在 feature 分支上意外合并上游代码。

const currentBranch = execSync("git rev-parse --abbrev-ref HEAD")
  .toString()
  .trim();
if (currentBranch !== "main") {
  throw new Error(`仅支持在 main 分支执行更新，当前分支: ${currentBranch}`);
}

2. 检查工作区状态

git status --porcelain

作用：以机器可读的格式输出工作区状态。

参数解析：

--porcelain：输出稳定、易于解析的格式，不受 Git 版本和语言设置影响

输出格式：

M  modified-file.ts      # 已暂存的修改
 M unstaged-file.ts      # 未暂存的修改
?? untracked-file.ts     # 未跟踪的文件
A  new-file.ts           # 新添加的文件
D  deleted-file.ts       # 删除的文件

前两个字符分别表示暂存区和工作区的状态。

const statusOutput = execSync("git status --porcelain").toString();
const uncommittedFiles = statusOutput.split("\n").filter((line) => line.trim());
const isClean = uncommittedFiles.length === 0;

3. 管理远程仓库

检查 remote 是否存在

git remote get-url upstream

作用：获取指定 remote 的 URL，如果不存在会报错。

添加 upstream remote

# 将 URL 替换为你的上游仓库地址
git remote add upstream https://github.com/original/repo.git

作用：添加一个名为 upstream 的远程仓库，指向原始项目。

为什么需要 upstream？

当你 fork 一个项目后，你的 origin 指向你自己的 fork，而 upstream 指向原始项目。这样可以：

从 upstream 拉取原项目的更新
向 origin 推送你的修改

// UPSTREAM_URL 需替换为你的上游仓库地址
const UPSTREAM_URL = "https://github.com/original/repo.git";

function ensureUpstreamRemote(): string {
  try {
    return execSync("git remote get-url upstream").toString().trim();
  } catch {
    execSync(`git remote add upstream ${UPSTREAM_URL}`);
    return UPSTREAM_URL;
  }
}

4. 获取远程更新

git fetch upstream

作用：从 upstream 远程仓库下载所有分支的最新提交，但不会自动合并到本地分支。

与 git pull 的区别：

fetch 只下载数据，不修改本地代码
pull = fetch + merge，会自动合并

使用 fetch 可以让我们先预览变更，再决定是否合并。

5. 计算提交差异

git rev-list --left-right --count HEAD...upstream/main

作用：计算本地分支与 upstream/main 之间的提交差异。

参数解析：

rev-list：列出提交记录
--left-right：区分左侧（本地）和右侧（远程）的提交
--count：只输出计数，不列出具体提交
HEAD...upstream/main：三个点表示对称差集

输出示例：

2    5

表示本地有 2 个提交不在 upstream 上（ahead），upstream 有 5 个提交不在本地（behind）。

const revList = execSync(
  "git rev-list --left-right --count HEAD...upstream/main"
)
  .toString()
  .trim();
const [aheadStr, behindStr] = revList.split("\t");
const aheadCount = parseInt(aheadStr, 10);
const behindCount = parseInt(behindStr, 10);

console.log(`本地领先 ${aheadCount} 个提交，落后 ${behindCount} 个提交`);

6. 查看待合并的提交

git log HEAD..upstream/main --pretty=format:"%h|%s|%ar|%an" --no-merges

作用：列出 upstream/main 上有但本地没有的提交。

参数解析：

HEAD..upstream/main：两个点表示 A 到 B 的差集（B 有而 A 没有的）
--pretty=format:"..."：自定义输出格式
- %h：短 hash
- %s：提交信息
- %ar：相对时间（如 “2 days ago”）
- %an：作者名
--no-merges：排除 merge commit

输出示例：

a1b2c3d|feat: add dark mode|2 days ago|Author Name
e4f5g6h|fix: typo in readme|3 days ago|Author Name

const commitFormat = "%h|%s|%ar|%an";
const output = execSync(
  `git log HEAD..upstream/main --pretty=format:"${commitFormat}" --no-merges`
).toString();

const commits = output
  .split("\n")
  .filter(Boolean)
  .map((line) => {
    const [hash, message, date, author] = line.split("|");
    return { hash, message, date, author };
  });

7. 查看远程文件内容

git show upstream/main:package.json

作用：直接查看远程分支上某个文件的内容，无需切换分支或合并。

使用场景：获取上游仓库的版本号，用于显示”将更新到 x.x.x 版本”。

const packageJson = execSync("git show upstream/main:package.json").toString();
const { version } = JSON.parse(packageJson);
console.log(`最新版本: ${version}`);

8. 执行合并

git merge upstream/main --no-edit

作用：将 upstream/main 分支合并到当前分支。

参数解析：

--no-edit：使用自动生成的合并提交信息，不打开编辑器

合并策略：Git 会自动选择合适的合并策略：

Fast-forward：如果本地没有新提交，直接移动指针
Three-way merge：如果有分叉，创建一个合并提交

注意：本工具采用 merge 同步上游，保留本地历史。如果你的需求是”强制与上游一致”（丢弃本地修改），需要使用 rebase 或 reset 方案，不在本文讨论范围。

9. 检测合并冲突

git diff --name-only --diff-filter=U

作用：列出所有未解决冲突的文件。

参数解析：

--name-only：只输出文件名
--diff-filter=U：只显示 Unmerged（未合并/冲突）的文件

另一种方式是解析 git status --porcelain 的输出，查找冲突标记：

const statusOutput = execSync("git status --porcelain").toString();
const conflictFiles = statusOutput
  .split("\n")
  .filter((line) => {
    const status = line.slice(0, 2);
    // U = Unmerged, AA = both added, DD = both deleted
    return status.includes("U") || status === "AA" || status === "DD";
  })
  // 注：为简化展示，这里直接截取路径
  // 若需完整兼容重命名/特殊路径，应使用更严格的 porcelain 解析
  .map((line) => line.slice(3).trim());

10. 中止合并

git merge --abort

作用：中止当前的合并操作，恢复到合并前的状态。

使用场景：当用户遇到冲突但不想手动解决时，可以选择中止合并。

function abortMerge(): boolean {
  try {
    execSync("git merge --abort");
    return true;
  } catch {
    return false;
  }
}

状态机设计

如果是简单粗暴的使用 useEffect 的话，会出现很多 useEffect 那自然很不好。

整个更新流程使用简单的 useReducer + Effect Map 模式管理，将状态转换逻辑和副作用处理分离，确保流程清晰可控。

为什么不用 Redux？

在设计 CLI 状态管理时，很自然会想到 Redux，毕竟它是 React 生态中最成熟的状态管理方案，而且还是用着 Ink 来进行开发的。但对于 CLI 工具，useReducer 是更合适的选择，理由如下：

状态作用域单一：CLI 工具通常是单组件树结构，不存在跨页面、跨路由的状态共享需求，
无需 Middleware 生态：Redux 的强大之处在于中间件生态（redux-thunk、redux-saga、redux-observable），用于处理复杂的异步流程。但我们的场景不需要那么复杂。
依赖最小化：CLI 工具应该快速启动、轻量运行。useReducer 内置于 React，不会引入额外依赖（当然 React 本身也是依赖，不过我的项目里本来就需要它）

总之，对这个场景来说 Redux 有点”过度设计”。

那咋整？

Reducer：集中管理所有状态转换逻辑，纯函数易于测试
Effect Map：状态到副作用的映射，统一处理异步操作
单一 Effect：一个 useEffect 驱动整个流程

下面是完整的状态转换流程图，展示了所有可能的状态转换路径和条件分支：

注意：Mermaid stateDiagram 中状态名不能包含连字符 -，这里使用 camelCase 命名。

stateDiagram-v2
    [*] --> checking: 开始更新

    checking --> error: 不在 main 分支
    checking --> dirtyWarning: 工作区不干净 && !force
    checking --> fetching: 工作区干净 || force

    dirtyWarning --> [*]: 用户取消
    dirtyWarning --> fetching: 用户继续

    fetching --> upToDate: behindCount = 0
    fetching --> backupConfirm: behindCount > 0 && !skipBackup
    fetching --> preview: behindCount > 0 && skipBackup

    backupConfirm --> backingUp: 用户确认备份
    backupConfirm --> preview: 用户跳过备份

    backingUp --> preview: 备份完成
    backingUp --> error: 备份失败

    preview --> [*]: checkOnly 模式
    preview --> merging: 用户确认更新
    preview --> [*]: 用户取消

    merging --> conflict: 合并冲突
    merging --> installing: 合并成功

    conflict --> [*]: 用户处理冲突

    installing --> done: 依赖安装成功
    installing --> error: 依赖安装失败

    done --> [*]
    error --> [*]
    upToDate --> [*]

类型定义

// 12 种状态覆盖完整流程
type UpdateStatus =
  | "checking" // 检查 Git 状态
  | "dirty-warning" // 工作区有未提交更改
  | "backup-confirm" // 确认备份
  | "backing-up" // 正在备份
  | "fetching" // 获取更新
  | "preview" // 显示更新预览
  | "merging" // 合并中
  | "installing" // 安装依赖
  | "done" // 完成
  | "conflict" // 有冲突
  | "up-to-date" // 已是最新
  | "error"; // 错误

// Action 驱动状态转换
type UpdateAction =
  | { type: "GIT_CHECKED"; payload: GitStatusInfo }
  | { type: "FETCHED"; payload: UpdateInfo }
  | { type: "BACKUP_CONFIRM" | "BACKUP_SKIP" | "UPDATE_CONFIRM" | "INSTALLED" }
  | { type: "BACKUP_DONE"; backupFile: string }
  | { type: "MERGED"; payload: MergeResult }
  | { type: "ERROR"; error: string };

Reducer 集中状态转换

所有状态转换逻辑集中在 reducer 中，每个 case 只处理当前状态下合法的 action：

function updateReducer(state: UpdateState, action: UpdateAction): UpdateState {
  const { status, options } = state;

  // 通用错误处理：任何状态都可以转到 error
  if (action.type === "ERROR") {
    return { ...state, status: "error", error: action.error };
  }

  switch (status) {
    case "checking": {
      if (action.type !== "GIT_CHECKED") return state;
      const { payload: gitStatus } = action;

      if (gitStatus.currentBranch !== "main") {
        return {
          ...state,
          status: "error",
          error: "仅支持在 main 分支执行更新",
        };
      }
      if (!gitStatus.isClean && !options.force) {
        return { ...state, status: "dirty-warning", gitStatus };
      }
      return { ...state, status: "fetching", gitStatus };
    }

    case "fetching": {
      if (action.type !== "FETCHED") return state;
      const { payload: updateInfo } = action;

      if (updateInfo.behindCount === 0) {
        return { ...state, status: "up-to-date", updateInfo };
      }
      const nextStatus = options.skipBackup ? "preview" : "backup-confirm";
      return { ...state, status: nextStatus, updateInfo };
    }

    // ... 其他状态处理
  }
}

Effect Map：统一副作用处理

每个需要执行副作用的状态对应一个 effect 函数，可返回 cleanup 函数：

type EffectFn = (
  state: UpdateState,
  dispatch: Dispatch<UpdateAction>
) => (() => void) | undefined;

const statusEffects: Partial<Record<UpdateStatus, EffectFn>> = {
  checking: (_state, dispatch) => {
    const gitStatus = checkGitStatus();
    ensureUpstreamRemote();
    dispatch({ type: "GIT_CHECKED", payload: gitStatus });
    return undefined;
  },

  fetching: (_state, dispatch) => {
    fetchUpstream();
    const info = getUpdateInfo();
    dispatch({ type: "FETCHED", payload: info });
    return undefined;
  },

  installing: (_state, dispatch) => {
    let cancelled = false;
    installDeps().then((result) => {
      if (cancelled) return;
      dispatch(
        result.success
          ? { type: "INSTALLED" }
          : { type: "ERROR", error: result.error }
      );
    });
    return () => {
      cancelled = true;
    }; // cleanup
  },
};

组件使用

组件中只需一个核心 useEffect 来驱动整个状态机：

function UpdateApp({ checkOnly, skipBackup, force }) {
  const [state, dispatch] = useReducer(
    updateReducer,
    { checkOnly, skipBackup, force },
    createInitialState
  );

  // 核心：单一 effect 处理所有副作用
  useEffect(() => {
    const effect = statusEffects[state.status];
    if (!effect) return;
    return effect(state, dispatch);
  }, [state.status, state]);

  // UI 渲染基于 state.status
  return <Box>...</Box>;
}

这种模式的优势：

可测试性：Reducer 是纯函数，可以独立测试状态转换
可维护性：状态逻辑集中，不会分散在多个 useEffect 中
可扩展性：添加新状态只需在 reducer 和 effect map 各加一个 case

用户交互设计

使用 React Ink 构建终端 UI，提供友好的交互体验：

预览更新

发现 5 个新提交:
  a1b2c3d feat: add dark mode (2 days ago)
  e4f5g6h fix: responsive layout (3 days ago)
  i7j8k9l docs: update readme (1 week ago)
  ... 还有 2 个提交

注意: 本地有 1 个未推送的提交

确认更新到最新版本？ (Y/n)

处理冲突

发现合并冲突
冲突文件:
  - src/config.ts
  - src/components/Header.tsx

你可以:
  1. 手动解决冲突后运行: git add . && git commit
  2. 中止合并恢复到更新前状态

备份文件: backup-2026-01-10-full.tar.gz

是否中止合并？ (Y/n)

完整代码实现

Git 操作封装

import { execSync } from "node:child_process";

function git(args: string): string {
  return execSync(`git ${args}`, {
    encoding: "utf-8",
    stdio: ["pipe", "pipe", "pipe"],
  }).trim();
}

function gitSafe(args: string): string | null {
  try {
    return git(args);
  } catch {
    return null;
  }
}

export function checkGitStatus(): GitStatusInfo {
  const currentBranch = git("rev-parse --abbrev-ref HEAD");
  const statusOutput = gitSafe("status --porcelain") || "";
  const uncommittedFiles = statusOutput
    .split("\n")
    .filter((line) => line.trim());

  return {
    currentBranch,
    isClean: uncommittedFiles.length === 0,
    // 注：简化处理，完整兼容需更严格的 porcelain 解析
    uncommittedFiles: uncommittedFiles.map((line) => line.slice(3).trim()),
  };
}

export function getUpdateInfo(): UpdateInfo {
  const revList =
    gitSafe("rev-list --left-right --count HEAD...upstream/main") || "0\t0";
  const [aheadStr, behindStr] = revList.split("\t");

  const commitFormat = "%h|%s|%ar|%an";
  const commitsOutput =
    gitSafe(
      `log HEAD..upstream/main --pretty=format:"${commitFormat}" --no-merges`
    ) || "";

  const commits = commitsOutput
    .split("\n")
    .filter(Boolean)
    .map((line) => {
      const [hash, message, date, author] = line.split("|");
      return { hash, message, date, author };
    });

  return {
    behindCount: parseInt(behindStr, 10),
    aheadCount: parseInt(aheadStr, 10),
    commits,
  };
}

export function mergeUpstream(): MergeResult {
  try {
    git("merge upstream/main --no-edit");
    return { success: true, hasConflict: false, conflictFiles: [] };
  } catch {
    const conflictFiles = getConflictFiles();
    return {
      success: false,
      hasConflict: conflictFiles.length > 0,
      conflictFiles,
    };
  }
}

function getConflictFiles(): string[] {
  const output = gitSafe("diff --name-only --diff-filter=U") || "";
  return output.split("\n").filter(Boolean);
}

Git 命令速查表

命令	作用	场景
`git rev-parse --abbrev-ref HEAD`	获取当前分支名	验证分支
`git status --porcelain`	机器可读的状态输出	检查工作区
`git remote get-url <name>`	获取 remote URL	检查 remote
`git remote add <name> <url>`	添加 remote	配置 upstream
`git fetch <remote>`	下载远程更新	获取更新
`git rev-list --left-right --count A...B`	统计差异提交数	计算 ahead/behind
`git log A..B --pretty=format:"..."`	列出差异提交	预览更新
`git show <ref>:<path>`	查看远程文件	获取版本号
`git merge <branch> --no-edit`	自动合并	执行更新
`git diff --name-only --diff-filter=U`	列出冲突文件	检测冲突
`git merge --abort`	中止合并	回滚操作

Git 命令功能分类

为了更好地理解这些命令的用途，下面按功能将它们分类展示：

infographic hierarchy-structure
data
  title Git 命令功能分类
  desc 按操作类型组织的命令清单
  items
    - label 状态检查
      icon mdi/information
      children
        - label git rev-parse
          desc 获取当前分支名
        - label git status --porcelain
          desc 检查工作区状态
    - label 远程管理
      icon mdi/server-network
      children
        - label git remote get-url
          desc 检查 remote 是否存在
        - label git remote add
          desc 添加 upstream remote
        - label git fetch
          desc 下载远程更新
    - label 提交分析
      icon mdi/source-commit
      children
        - label git rev-list
          desc 统计提交差异
        - label git log
          desc 查看提交历史
        - label git show
          desc 查看远程文件内容
    - label 合并操作
      icon mdi/source-merge
      children
        - label git merge
          desc 执行分支合并
        - label git merge --abort
          desc 中止合并恢复状态
    - label 冲突检测
      icon mdi/alert-octagon
      children
        - label git diff --diff-filter=U
          desc 列出未解决冲突文件

备份还原功能实现

除了主题更新，CLI 还提供了完整的备份还原功能，确保用户数据安全。

备份和还原是两个互补的操作，下图展示了它们的完整工作流：

infographic compare-hierarchy-row-letter-card-compact-card
data
  title 备份与还原流程对比
  desc 两个互补操作的完整工作流
  items
    - label 备份流程
      icon mdi/backup-restore
      children
        - label 检查配置
          desc 确定备份类型和范围
        - label 创建临时目录
          desc 准备暂存空间
        - label 复制文件
          desc 按配置复制所需文件
        - label 生成 manifest
          desc 记录版本和元信息
        - label 压缩打包
          desc tar.gz 压缩存档
        - label 清理临时目录
          desc 删除暂存目录
    - label 还原流程
      icon mdi/restore
      children
        - label 选择备份
          desc 读取 manifest 显示备份信息
        - label 解压到临时目录
          desc 提取归档内容（包含 manifest）
        - label 读取 manifest.files
          desc 获取实际备份成功的文件列表
        - label 按映射复制文件
          desc 使用自动生成的 RESTORE_MAP
        - label 清理临时目录
          desc 删除解压的暂存文件

备份项配置

备份系统采用配置驱动的方式，定义需要备份的文件和目录：

export interface BackupItem {
  src: string; // 源路径（相对于项目根目录）
  dest: string; // 备份内目标路径
  label: string; // 显示标签
  required: boolean; // 是否为必需项（basic 模式包含）
}

export const BACKUP_ITEMS: BackupItem[] = [
  // 基础备份项（required: true）
  {
    src: "src/content/blog",
    dest: "content/blog",
    label: "博客文章",
    required: true,
  },
  {
    src: "config/site.yaml",
    dest: "config/site.yaml",
    label: "网站配置",
    required: true,
  },
  {
    src: "src/pages/about.md",
    dest: "pages/about.md",
    label: "关于页面",
    required: true,
  },
  {
    src: "public/img/avatar.webp",
    dest: "img/avatar.webp",
    label: "用户头像",
    required: true,
  },
  { src: ".env", dest: "env", label: "环境变量", required: true },
  // 完整备份额外项目（required: false）
  { src: "public/img", dest: "img", label: "所有图片", required: false },
  {
    src: "src/assets/lqips.json",
    dest: "assets/lqips.json",
    label: "LQIP 数据",
    required: false,
  },
  {
    src: "src/assets/similarities.json",
    dest: "assets/similarities.json",
    label: "相似度数据",
    required: false,
  },
  {
    src: "src/assets/summaries.json",
    dest: "assets/summaries.json",
    label: "AI 摘要数据",
    required: false,
  },
];

备份流程

备份操作使用 tar.gz 格式压缩，并生成 manifest.json 记录元信息：

export function runBackup(
  isFullBackup: boolean,
  onProgress?: (results: BackupResult[]) => void
): BackupOutput {
  // 1. 创建备份目录和临时目录
  fs.mkdirSync(BACKUP_DIR, { recursive: true });
  const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
  const tempDir = path.join(BACKUP_DIR, `.tmp-backup-${timestamp}`);

  // 2. 过滤备份项目（基础备份只包含 required: true 的项目）
  const itemsToBackup = BACKUP_ITEMS.filter(
    (item) => item.required || isFullBackup
  );

  // 3. 复制文件到临时目录
  const results: BackupResult[] = [];
  for (const item of itemsToBackup) {
    const srcPath = path.join(PROJECT_ROOT, item.src);
    const destPath = path.join(tempDir, item.dest);

    if (fs.existsSync(srcPath)) {
      fs.cpSync(srcPath, destPath, { recursive: true });
      results.push({ item, success: true, skipped: false });
    } else {
      results.push({ item, success: false, skipped: true });
    }
    onProgress?.([...results]); // 进度回调
  }

  // 4. 生成 manifest.json
  const manifest = {
    name: "astro-koharu-backup",
    version: getVersion(),
    type: isFullBackup ? "full" : "basic",
    timestamp,
    created_at: new Date().toISOString(),
    files: Object.fromEntries(results.map((r) => [r.item.dest, r.success])),
  };
  fs.writeFileSync(
    path.join(tempDir, "manifest.json"),
    JSON.stringify(manifest, null, 2)
  );

  // 5. 压缩并清理
  tarCreate(backupFilePath, tempDir);
  fs.rmSync(tempDir, { recursive: true, force: true });

  return { results, backupFile: backupFilePath, fileSize, timestamp };
}

tar 操作封装

使用系统 tar 命令进行压缩和解压，并添加路径遍历安全检查：

// 安全验证：防止路径遍历攻击
function validateTarEntries(entries: string[], archivePath: string): void {
  for (const entry of entries) {
    if (entry.includes("\0")) {
      throw new Error(`tar entry contains null byte`);
    }
    const normalized = path.posix.normalize(entry);
    if (path.posix.isAbsolute(normalized)) {
      throw new Error(`tar entry is absolute path: ${entry}`);
    }
    if (normalized.split("/").includes("..")) {
      throw new Error(`tar entry contains parent traversal: ${entry}`);
    }
  }
}

// 创建压缩包
export function tarCreate(archivePath: string, sourceDir: string): void {
  spawnSync("tar", ["-czf", archivePath, "-C", sourceDir, "."]);
}

// 解压到指定目录
export function tarExtract(archivePath: string, destDir: string): void {
  listTarEntries(archivePath); // 先验证条目安全性
  spawnSync("tar", ["-xzf", archivePath, "-C", destDir]);
}

// 读取 manifest（不解压整个文件）
export function tarExtractManifest(archivePath: string): string | null {
  const result = spawnSync("tar", ["-xzf", archivePath, "-O", "manifest.json"]);
  return result.status === 0 ? result.stdout : null;
}

还原流程

还原操作基于 manifest 驱动，确保只还原实际备份成功的文件：

// 路径映射：从备份项配置自动生成，确保一致性
export const RESTORE_MAP: Record<string, string> = Object.fromEntries(
  BACKUP_ITEMS.map((item) => [item.dest, item.src])
);

export function restoreBackup(backupPath: string): RestoreResult {
  // 1. 创建临时目录并解压
  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "restore-"));
  tarExtract(backupPath, tempDir);

  // 2. 读取 manifest 获取实际备份的文件列表
  const manifestPath = path.join(tempDir, "manifest.json");
  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));

  const restored: string[] = [];
  const skipped: string[] = [];

  // 3. 基于 manifest.files 还原（只还原成功备份的文件）
  for (const [backupPath, success] of Object.entries(manifest.files)) {
    // 跳过备份失败的文件
    if (!success) {
      skipped.push(backupPath);
      continue;
    }

    const projectPath = RESTORE_MAP[backupPath];
    if (!projectPath) {
      console.warn(`未知的备份路径: ${backupPath}，跳过`);
      skipped.push(backupPath);
      continue;
    }

    const srcPath = path.join(tempDir, backupPath);
    const destPath = path.join(PROJECT_ROOT, projectPath);

    if (fs.existsSync(srcPath)) {
      fs.mkdirSync(path.dirname(destPath), { recursive: true });
      fs.cpSync(srcPath, destPath, { recursive: true });
      restored.push(projectPath);
    } else {
      skipped.push(backupPath);
    }
  }

  // 4. 清理临时目录
  fs.rmSync(tempDir, { recursive: true, force: true });

  return {
    restored,
    skipped,
    backupType: manifest.type,
    version: manifest.version,
  };
}

Dry-Run 模式详解

Dry-run（预演模式）是 CLI 工具中常见的安全特性，允许用户在实际执行前预览操作结果。本实现采用函数分离 + 条件渲染的模式。

下图展示了预览模式和实际执行模式的核心区别：

infographic compare-binary-horizontal-badge-card-arrow
data
  title Dry-Run 模式与实际执行对比
  desc 预览模式和实际还原的关键区别
  items
    - label 预览模式
      desc 安全的只读预览
      icon mdi/eye
      children
        - label 提取 manifest.json
          desc 调用 tarExtractManifest 不解压整个归档
        - label 读取 manifest.files
          desc 获取实际备份的文件列表
        - label 统计文件数量
          desc 调用 tarList 计算每个路径的文件数
        - label 不修改任何文件
          desc 零副作用,可安全执行
    - label 实际执行
      desc 基于 manifest 的还原
      icon mdi/content-save
      children
        - label 解压整个归档
          desc 调用 tarExtract 提取所有文件
        - label 读取 manifest.files
          desc 获取实际备份成功的文件列表
        - label 按 manifest 复制文件
          desc 只还原 success: true 的文件
        - label 显示跳过的文件
          desc 报告 success: false 的文件

预览函数和执行函数

关键在于提供两个功能相似但副作用不同的函数：

// 预览函数：只读取 manifest，不解压不修改文件
export function getRestorePreview(backupPath: string): RestorePreviewItem[] {
  // 只提取 manifest.json，不解压整个归档
  const manifestContent = tarExtractManifest(backupPath);
  if (!manifestContent) {
    throw new Error("无法读取备份 manifest");
  }

  const manifest = JSON.parse(manifestContent);
  const previewItems: RestorePreviewItem[] = [];

  // 基于 manifest.files 生成预览
  for (const [backupPath, success] of Object.entries(manifest.files)) {
    if (!success) continue; // 跳过备份失败的文件

    const projectPath = RESTORE_MAP[backupPath];
    if (!projectPath) continue;

    // 从归档中统计文件数量（不解压）
    const files = tarList(backupPath);
    const matchingFiles = files.filter(
      (f) => f === backupPath || f.startsWith(`${backupPath}/`)
    );
    const fileCount = matchingFiles.length;

    previewItems.push({
      path: projectPath,
      fileCount: fileCount || 1,
      backupPath,
    });
  }

  return previewItems;
}

// 执行函数：实际解压并复制文件
export function restoreBackup(backupPath: string): RestoreResult {
  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "restore-"));
  tarExtract(backupPath, tempDir); // 实际解压

  // 读取 manifest 驱动还原
  const manifest = JSON.parse(
    fs.readFileSync(path.join(tempDir, "manifest.json"), "utf-8")
  );

  const restored: string[] = [];
  for (const [backupPath, success] of Object.entries(manifest.files)) {
    if (!success) continue;
    const projectPath = RESTORE_MAP[backupPath];
    // ... 实际复制文件
    fs.cpSync(srcPath, destPath, { recursive: true });
    restored.push(projectPath);
  }

  return { restored, skipped: [], backupType: manifest.type };
}

两个函数的核心区别：

预览：调用 tarExtractManifest() 只提取 manifest，再用 tarList() 统计文件数量
执行：调用 tarExtract() 解压整个归档，基于 manifest.files 复制文件

组件层：条件分发

在 React 组件中，根据 dryRun 参数决定调用哪个函数：

interface RestoreAppProps {
  dryRun?: boolean; // 是否为预览模式
  force?: boolean; // 是否跳过确认
}

export function RestoreApp({ dryRun = false, force = false }: RestoreAppProps) {
  const [result, setResult] = useState<{
    items: RestorePreviewItem[] | string[];
    backupType?: string;
    skipped?: string[];
  }>();

  // 预览模式：只读取 manifest
  const runDryRun = useCallback(() => {
    const previewItems = getRestorePreview(selectedBackup);
    setResult({ items: previewItems });
    setStatus("done");
  }, [selectedBackup]);

  // 实际还原：基于 manifest 执行还原
  const runRestore = useCallback(() => {
    setStatus("restoring");
    const { restored, skipped, backupType } = restoreBackup(selectedBackup);
    setResult({ items: restored, backupType, skipped });
    setStatus("done");
  }, [selectedBackup]);

  // 确认时根据模式分发
  function handleConfirm() {
    if (dryRun) {
      runDryRun();
    } else {
      runRestore();
    }
  }
}

关键设计：

统一数据结构：result 可以容纳预览和执行两种结果
类型区分：预览返回 RestorePreviewItem[]（含 fileCount），执行返回 string[]
额外信息：执行模式返回 backupType 和 skipped，用于显示完整信息

UI 层：差异化展示

预览模式和实际执行模式在 UI 上有明确区分：

{
  /* 确认提示：显示备份类型和文件数量 */
}
<Text color="yellow">
  {dryRun ? "[预览模式] " : ""}
  确认还原 {result?.backupType} 备份? 此操作将覆盖现有文件
</Text>;

{
  /* 完成状态：根据模式显示不同标题 */
}
<Text bold color="green">
  {dryRun ? "预览模式" : "还原完成"}
</Text>;

{
  /* 结果展示：预览模式显示文件数量统计 */
}
{
  result?.items.map((item) => {
    const isPreviewItem = typeof item !== "string";
    const filePath = isPreviewItem ? item.path : item;
    const fileCount = isPreviewItem ? item.fileCount : 0;
    return (
      <Text key={filePath}>
        <Text color="green">{"  "}+ </Text>
        <Text>{filePath}</Text>
        {/* 预览模式额外显示文件数量 */}
        {isPreviewItem && fileCount > 1 && (
          <Text dimColor> ({fileCount} 文件)</Text>
        )}
      </Text>
    );
  });
}

{
  /* 统计文案：使用 "将" vs "已" 区分 */
}
<Text>
  {dryRun ? "将" : "已"}还原: <Text color="green">{result?.items.length}</Text>{" "}
  项
</Text>;

{
  /* 显示跳过的文件（仅实际执行模式） */
}
{
  !dryRun && result?.skipped && result.skipped.length > 0 && (
    <Box flexDirection="column" marginTop={1}>
      <Text color="yellow">跳过的文件:</Text>
      {result.skipped.map((file) => (
        <Text key={file} dimColor>
          {"  "}- {file}
        </Text>
      ))}
    </Box>
  );
}

{
  /* 预览模式特有提示 */
}
{
  dryRun && <Text color="yellow">这是预览模式，没有文件被修改</Text>;
}

{
  /* 实际执行模式：显示后续步骤 */
}
{
  !dryRun && (
    <Box flexDirection="column" marginTop={1}>
      <Text dimColor>后续步骤:</Text>
      <Text dimColor>{"  "}1. pnpm install # 安装依赖</Text>
      <Text dimColor>{"  "}2. pnpm build # 构建项目</Text>
    </Box>
  );
}

命令行使用

# 预览模式：查看将要还原的内容
pnpm koharu restore --dry-run

# 实际执行
pnpm koharu restore

# 跳过确认直接执行
pnpm koharu restore --force

# 还原最新备份（预览）
pnpm koharu restore --latest --dry-run

输出对比

预览模式输出（Full 备份）：

备份文件: backup-2026-01-10-12-30-00-full.tar.gz
备份类型: full
主题版本: 1.2.0
备份时间: 2026-01-10 12:30:00

[预览模式] 确认还原 full 备份? 此操作将覆盖现有文件 (Y/n)

预览模式
  + src/content/blog (42 文件)
  + config/site.yaml
  + src/pages/about.md
  + .env
  + public/img (128 文件)
  + src/assets/lqips.json
  + src/assets/similarities.json
  + src/assets/summaries.json

将还原: 8 项
这是预览模式，没有文件被修改

预览模式输出（Basic 备份）：

备份文件: backup-2026-01-10-12-30-00-basic.tar.gz
备份类型: basic
主题版本: 1.2.0
备份时间: 2026-01-10 12:30:00

[预览模式] 确认还原 basic 备份? 此操作将覆盖现有文件 (Y/n)

预览模式
  + src/content/blog (42 文件)
  + config/site.yaml
  + src/pages/about.md
  + .env
  + public/img/avatar.webp

将还原: 5 项
这是预览模式，没有文件被修改

实际执行输出（含跳过的文件）：

还原完成
  + src/content/blog
  + config/site.yaml
  + src/pages/about.md
  + .env
  + public/img

跳过的文件:
  - src/assets/lqips.json (备份时不存在)

已还原: 5 项
后续步骤:
  1. pnpm install # 安装依赖
  2. pnpm build # 构建项目
  3. pnpm dev # 启动开发服务器

写在最后

能看到这里，那很厉害了，觉得还挺喜欢的话，欢迎给我一个 star 呢～

github.com

GitHub - cosZone/astro-koharu: astro-koharu 是一个萌系/二次元/粉蓝配色的 astro 主题博客，灵感来自 Hexo 的 Shoka 主题，加了很多自己的小巧思，性能优越。

astro-koharu 是一个萌系/二次元/粉蓝配色的 astro 主题博客，灵感来自 Hexo 的 Shoka 主题，加了很多自己的小巧思，性能优越。 - cosZone/astro-koharu

https://github.com/cosZone/astro-koharu

自认为这次实现的这个 CLI 对于我自己的需求来说，相当好用，只恨没有早一些实践，如果你看到这篇文章，可以放心大胆的去构建。

React Ink

Ink - GitHub - React for interactive command-line apps，官方仓库
Ink UI - Ink 的 UI 组件库，提供 TextInput、Spinner、ProgressBar 等组件
Using Ink UI with React to build interactive, custom CLIs - LogRocket - Ink UI 使用教程
Building a Coding CLI with React Ink - 实战教程，包含流式输出实现
React + Ink CLI Tutorial - FreeCodeCamp - 入门教程
Node.js CLI Apps Best Practices - GitHub - Node.js CLI 最佳实践清单

Git 同步 Fork

Syncing a fork - GitHub Docs - 官方文档
Git Upstreams and Forks - Atlassian - Atlassian 的详细教程
How to Sync Your Fork with the Original Git Repository - FreeCodeCamp - 完整同步指南

状态机与 useReducer

How to Use useReducer as a Finite State Machine - Kyle Shevlin - 将 useReducer 用作状态机的经典文章
Turning your React Component into a Finite State Machine - DEV - 状态机实战教程

FE Bits Vol.22 | CSS @scope 全面可用，ViteLand 12 月回顾

Sun, 11 Jan 2026 11:30:00 GMT

本期网址 https://blog.cosine.ren/post/weekly-22
本周刊更新时间期望是在每周天。
推荐订阅本周刊的 RSS。
公众号前端周周谈 FE Bits，点击阅读原文链接可查看原文。
QQ 讨论小群 598022684 / Discord 群
本周刊文章内容同时也开源在 fe-bits-weekly，欢迎关注。

今天是 2026 年 1 月 11 日，星期天。

年终总结在写了（还在写？）

建了个 discord 群，虽然不怎么上 discord（）

discord.com

Join the Cos 的 Discord 小窝 Discord Server!

不知道做什么的服务器。比较随便。因为后知后觉的意识到虽然我用 tg 聊天比较多，但是 discord 群作为公开群好像比较合适比较方便（嗯？）总之想找我聊天的可以加，后续应该会作为各种项目里边 link 的公开群。 | 34 members

https://discord.gg/XzvrvNMcSe

因为后知后觉的意识到 Discord 群作为公开群好像比较合适比较方便（嗯）

总之想找我聊天或者问问题的都可以加，后续应该会作为各种项目里边 link 的公开群。

然后是博客主题更新，新增了 Koharu CLI 交互式命令行工具，提供博客内容备份/还原、主题更新、内容生成、备份管理等功能。配置文件也统一更改为 config/site.yaml 了。

github.com

Release v2.0.0 · cosZone/astro-koharu

What’s Changed Feat/yaml by @yusixian in #42 Build/backup by @yusixian in #43 Full Changelog: v1.4.0...v2.0.0 Breaking Changes 配置文件统一更改为 config/site.yaml Umami 分析配置从环境变量移至 site.yaml Remark42 配置移…

https://github.com/cosZone/astro-koharu/releases/tag/v2.0.0

然后觉得还挺有意思的，之后准备写一篇博客简单讲讲（实现交互式 Git 主题更新 CLI 的完整方案）

上架了 astro 主题商店，发了一篇 v2ex 帖子。

astro.build

Koharu | Astro

astro-koharu is a cute ACG pink and blue color Astro themed blog. It is inspired by the Shoka theme of Hexo and features many of its own ingenious touches. It has excellent performance.

https://astro.build/themes/details/koharu

v2ex.com

写了一个 Astro 博客主题 Koharu，加了一点点前端魔法～ - V2EX

分享创造 - @cosyu - 极简的主题超级多，来贡献一点点花里胡哨风的主题。（其实一开始，只是想简单做做，不知道为什么就变成现在这样啦）已经在 astro 主题商店上架啦～主题： https://astr

https://v2ex.com/t/1184086

并且 Moe Copy AI 插件上架火狐商店了（没想到不怎么需要适配）

addons.mozilla.org

Moe Copy AI – 下载 Firefox 扩展（zh-CN）

下载 Firefox 上的 Moe Copy AI。MoeCopy AI 是一款智能网页内容提取工具，能够准确抓取文章、元数据和图片，输出为 Markdown/HTML/纯文本格式，为 AI 模型提供高质量输入。

https://addons.mozilla.org/zh-CN/firefox/addon/moe-copy-ai/

社区动态

CSS `@scope` 规则已广泛可用

CSS @scope 已获得所有主流浏览器支持，该规则允许您选择特定 DOM 子树中的元素，精确定位元素，而无需编写难以覆盖的过于具体的选择器。

MDN：@scope - CSS | MDN
文章：How to @scope CSS Now That It’s Baseline

用法形如

@scope (.article-body) to (figure) {
  img {
    border: 5px solid black;
    background-color: goldenrod;
  }
}

ViteLand 12 月回顾

What’s New in ViteLand: December 2025 Recap：ViteLand 生态在 2025 年 12 月迎来了一系列重要更新，涵盖了 Vite、Vitest、Rolldown、Oxc 等项目。

Oxlint 和 Oxfmt 如今已能取代传统工具，而且还在不断改进。可以查看 2026 年路线图

期待能在项目里广泛使用的那天！

Oxc 的性能突破
- Oxlint 和 Oxfmt 在代码校验（linting）和格式化（formatting）方面提供比 ESLint 和 Prettier 更快的速度（分别快 50-100 倍和 30 倍）。
- Oxlint 已推出 1.0 版本，并新增了类型感知校验（type-aware linting）和兼容 ESLint 的 JS 插件。
- Oxfmt 新增了对嵌入式语言和实验性导入排序的支持。
- Bun、Vue、Preact、date-fns、Inquirer.js、Shopify、Miro、Airbnb 等多个项目已迁移至 Oxc。
- Oxc 团队计划在 2026 年推出对动态配置（dynamic configs）的支持。
- Oxc 在性能优化方面持续投入，实现了语义分析性能的提升。
Vite 项目更新
- 发布了多个 Vite 8 beta 版本，修复了 bug 并提升了稳定性。
- Vite 8 beta 提供了第二版原生插件（native plugins），改进了动态导入（dynamic import）和导入 glob（import glob）插件的对齐。
Vitest 项目更新
- 新增实验性的 OpenTelemetry 支持，用于分析测试性能瓶颈。
- Vitest UI、CLI 和 VS Code 扩展支持分析和分解导入，识别减慢测试速度的依赖。
- 支持通过 experimental.fsCache 缓存转换后的文件，加速后续测试运行。
Rolldown 项目更新
- 支持通过手动指定 tsconfig 来使用 TypeScript 项目引用（TypeScript project references）。
- 优化了默认的代码块（chunking）算法，减少了生成的代码块数量。
- 提供了 postBanner 和 postFooter 选项，用于在打包后的代码前后追加内容。
- 插件的 resolveId 钩子支持通过 importerId 进行过滤，提高性能。
社区动态与合作
- Framer 发布了关于使用 Rolldown 改进性能的案例研究。
- TypeScript.fm 和 Syntax.fm 播客讨论了 ViteLand 项目的更新和发展预测。
- Ninja Squad 撰写了关于使用 Vitest 浏览器模式测试 Angular 的文章。
- 社区涌现出多个基于 Oxc 和 Rolldown 的新工具和迁移案例，如：
  - oxlint-plugin-complexity：用于校验代码复杂度的 Oxlint 插件。
  - Roll(down)phobia：基于 Rolldown 的包大小分析工具。
  - RSC Explorer：使用 Vite 8 和 Rolldown 构建的 RSC（React Server Components）工具。
  - Facetpack：使用 Oxc 替换 Babel 的 React Native 工具。
  - MonkeyType：迁移到 Oxlint 以获得更快的类型感知校验速度。
  - create-better-t-stack：从 Biome 迁移到 Oxlint 和 Oxfmt。
  - Ultracite：提供基于 Oxc 的预设配置。
  - rollipop：完全基于 Rolldown 的 React Native 构建工具。

文章与社区动态

Building a toast component：Emil 分享了制作 Sonner 时候的设计思路与技术实现，太细致了。
包大小调查：一步一步缩小 JavaScript 的指南：相当实用的好文，教你怎么减小打包体积，分析 JavaScript 打包大小、优化导入方式、解决重复库和处理传递依赖。
React 已发生变化，您的 hook 也应如此：当前主流项目仍以传统方式使用 React Hooks（如滥用 useEffect），忽视了 React 在并发模式与异步数据处理上的演变。作者从设计理念出发，提出现代 Hook 的核心精神是“架构化的状态与逻辑管理”，强调使用 useSyncExternalStore、useDeferredValue、useEffectEvent 等新 API 优化性能和可测试性，鼓励开发者更多关注派生状态（derived state）而非副作用（side effects）
AI 编码代理如何在我们的应用中隐藏定时炸弹: AI Agent 写代码的时候无意中在应用程序中引入了一个隐藏的、导致浏览器崩溃的无限 React 组件树，而 React 19 的 <Activity> 组件则巧妙地掩盖了这个问题。
require(esm) in Node.js: implementer’s tales：Joyee Cheung 是 Node.js 的核心贡献者之一，长期以来一直致力于 Node.js 对 require(esm) 的支持（即使用 require 加载 ES 模块）。在这篇系列文章中，她分两部分详细阐述了 require(esm) 实现历程及其具体细节。
超越鼠标：使用移动加速计制作动画：探讨了如何利用移动设备的加速计和运动传感器为网页动画注入动态交互，从而在移动设备上实现与桌面端鼠标交互相媲美的沉浸式用户体验。（这个我两年前有做过类似的需求，也叫陀螺仪，iOS 必须请求陀螺仪权限才能用，除了这个缺点，整体上其实用起来挺舒服的）
A first look at the Web Install API：探讨了新兴的 Web Install API，该 API 已在 Chromium 浏览器中进入 Origin Trial 阶段，并在 Microsoft Edge beta 版中展现出最完整的功能。此 API 的目标是允许网站通过简单的按钮点击直接安装 PWA (Progressive Web Apps)。相关链接: The Web Install API is ready for testing
Important and CSS Custom Properties：澄清了 CSS 自定义属性 (CSS Custom Properties) 中 !important 的作用机制，指出 !important 修饰的是声明本身而非其值，从而避免常见误解。
用 WebGL 着色器构建实时 ASCII 和抖动效果：很厉害的 ASCII 艺术生成网站 https://efecto.app/ 之前发过，这篇是作者的详细技术解析。
无限画布：建立一个无缝的，平铺任何地方的图像空间：很详细的教程，详细介绍了如何使用 React Three Fiber 构建一个无限可平移的图像画布，通过区块 (chunk) 渲染和性能优先的技术，创建一个流畅且可无尽探索的图像空间。

超越 RxJS: TanStack Pacer 指南：讲了怎么使用 TanStack Pacer 来管理前端应用中的异步事件时序，以优化性能并避免 RxJS 的复杂性。
VSCode 的 6 种快速的（原生）替代方案：本文探讨了广受欢迎的 VSCode 因其基于 Electron 的架构所带来的性能局限性，并介绍了六款用 C++、Rust 等原生语言开发的快速、高效的替代编辑器。
程序员和整洁的 Home：如何通过遵循 XDG Base Directory Specification (XDG BDS) 来整理混乱的 Home 目录，从而更好地管理配置文件、数据和缓存文件。
Vitest Browser Mode - The Future of Frontend Testing：介绍了 Vitest Browser Mode，可以在真实浏览器环境中进行前端组件测试。

新特性

重要信息 #2：条件视图转换、CSS/SVG 文本特效、最佳 CSS Bluesky 等：回顾了 2025 年末 CSS 领域的一些重要进展、新特性、社区讨论以及行业动态，并展望了 2026 年的趋势。
Date is out, Temporal is in：一篇 Temporal 的介绍。JavaScript Temporal 是 Date 的完美替代方案，已进入 TC39 标准化过程的第三阶段 (Stage 3)，在 Chrome 和 Firefox 等主流浏览器的最新版本中落地实现。
2026 年每个前端开发者都应该知道的 4 个 CSS 特性：介绍了前端开发者在 2026 年应该掌握的四个重要 CSS 新特性，包括 sibling-index()、@container scroll-state()、text-box 和 typed attr()。

工具

做友链功能的时候发现的，还挺好用的：DiceBear 是一个功能强大的头像库，旨在帮助设计师和开发者快速为项目创建多样化的头像。它提供了从抽象形状到精心设计的人物角色等多种头像风格。用户不仅可以生成随机头像，还可以通过设定 seed 实现确定性头像生成，或利用丰富的定制选项创建个性化头像。DiceBear 通过 JavaScript 库、HTTPS API、命令行工具 (CLI)、Figma 插件和在线 Playground 等多种方式提供。
Dither Image Online：一个免费、快速、实时的在线抖动（dithered）图像生成器，或者说像素艺术风格，效果太酷了！

你知道吗？可以通过在 GitHub 个人资料页面 URL 后添加 .png 来获取你的 GitHub 个人资料图片，例如 github․com/USERNAMEHERE.png - 还可以附加 .keys 来获取公钥，附加 .atom 来获取公开时间线活动的动态。Refernce

趣站与 Codepen 精选

GACHAGO! MarbleRace

非常可爱的网站！看了看首页还有很多有趣的东西

是一个基于物理模拟的弹珠台式抽奖工具，灵感来源于游戏内的抽奖玩法，通过模拟物理碰撞（例如红色柱子增加弹力）来决定结果，使得抽奖过程更具趣味性和不可预测性。

gachago.net

GACHAGO! - 線上抽獎、扭蛋、轉盤、骰子模擬網站

GACHAGO!! 是一個提供各種隨機線上抽獎的小工具網站，提供扭蛋、轉盤和骰子的線上模擬器。適合用來幫助你做決定！

https://www.gachago.net/MarbleRace

作者是 @Mant0uStudio

Mr. Panda’s Psychologically Safe Portfolio

很有创意的一个滚动驱动的 portfolio 页面：Mr. Panda’s Psychologically Safe Portfolio

开源在：GitHub - andrewwoan/mr-pandas-psychologically-safe-portfolio
技术解析文章：The Increasing Importance of Psychological Safety and Self-Awareness for Creative Work

像素化图片掉落特效

How to Create a Pixel-to-Voxel Video Drop Effect with Three.js and Rapier

这个教程详细介绍了如何利用 Three.js、着色器和 Rapier 物理引擎，将 2D 视频流转化为动态的 3D 体素 (voxel) 下落效果。文章从核心概念——像素和重力——出发，逐步讲解了如何构建一个由 InstancedMesh 和刚体 (rigid bodies) 组成的平面，通过着色器实现平铺像素到 3D 体素的涟漪 (ripple) 变形效果，并最终通过 JavaScript 模拟涟漪进程来激活物理引擎，使体素在逼真的物理作用下散射和恢复。作者还分享了实现过程中的技术细节、优化考量以及未来扩展的可能性。

Bongo Cat Codes #2 - Jamming

好萌，被萌到了

See the Pen qBOEzQa by carolineartz (@carolineartz) on CodePen.

果冻压扁按钮

你需要预留一点时间来压扁这个东西。无论是垂直拖动光标，还是单击 “跟随鼠标 “复选框，都可以将这个由 Voicu Apostol 制作的内含果冻的按钮的压扁效果与鼠标移动联系起来。

See the Pen LEZYxqM by cerpow (@cerpow) on CodePen.

好可爱的按钮！看了一下原理。

这不是真正的 3D 果冻，而是通过快速切换预渲染的图片序列来模拟果冻挤压效果，类似电影胶片的原理。预加载了 215 张连续的果冻形变图片，这些图片记录了果冻从静止到被挤压到回弹的完整动画过程，通过切换不同帧号的图片来做的。

文本框边框动画旋转 [CSS & SVG] V2

在 Fernando Cohen 制作的这个流畅的 CSS 和 SVG 动画中，文字栅栏围绕着一张照片的边缘。看看悬停照片时会发生什么，还可以看看他的 2022 年的早期迭代作品。

See the Pen OPyapww by designfenix (@designfenix) on CodePen.

看了一下原理，这是一个使用 SVG 和 CSS 创建的文字沿着有机形状边框旋转动画效果。

首先使用 SVG Blob 形状生成，创造有机的 blob 形状

<path d="M43.1,-68.5C56.2,-58.6,67.5,-47.3..." />

这个路径数据可能来自 Blob Generator 等工具

然后是使用 clip-path 进行图片裁剪，将矩形图片裁剪成 blob 形状，同时通过 preserveAspectRatio="xMidYMid slice" 确保图片填充满整个区域。

<clipPath id="blobClip">
  <path d="..." transform="translate(100 100)"/>
</clipPath>
<image clip-path="url(#blobClip)" />

然后使用 pathLength 进行文字路径动画，定义文字路径

<path id="text" d="..." fill="none" stroke="none" pathLength="100" />

pathLength="100" 标准化路径长度，便于动画计算
fill="none" stroke="none" 路径本身不可见，仅作为文字轨迹

将文字沿路径排列：

<text class="text-content">
  <textPath href="#text" startOffset="0%">
    ❤ MADE WITH LOVE ❤ MADE WITH LOVE...
    <animate attributeName="startOffset"
             from="0%" to="100%"
             dur="15s"
             repeatCount="indefinite" />
  </textPath>
</text>

<textPath> 让文字沿着指定路径排列
startOffset 控制文字在路径上的起始位置
<animate> 元素实现 SMIL 动画（SVG 原生动画）

那无缝循环是怎么做的呢？他用了两段文字，当第一段文字从 0% 移动到 100% 时，尾部会消失，第二段文字从 -100% 移动到 0%，正好填补空白。两段文字首尾相连，形成无缝循环。

<!-- 第一段文字：0% → 100% -->
<textPath href="#text" startOffset="0%">
  <animate from="0%" to="100%" />
</textPath>

<!-- 第二段文字：-100% → 0% -->
<textPath href="#text" startOffset="100%">
  <animate from="-100%" to="0%" />
</textPath>

最后是这个 交互式缩放效果，是通过悬停时放大裁剪区域（而非整个 SVG）来做的。

文摘

在谷歌工作 14 年的 21 条经验

最近读的有一篇文章感觉很棒，所以单独列出来。

每一条都是我赞同的！写得真好啊。

addyosmani.com

21 Lessons From 14 Years at Google

Lessons learned from 14 years of engineering at Google, focusing on what truly matters beyond just writing great code.

https://addyosmani.com/blog/21-lessons/

Addy Osmani 在 Google 14 年的职业生涯中，总结出 21 条经验教训。

以用户为中心
- 真正的价值来自于深入理解并解决用户问题，而非仅仅热衷于技术本身。
- 通过参与客服、与用户交谈、观察用户痛点来深入理解问题。
协作与对齐
- “对”固然重要，但“一起达成对”才是真正的挑战和价值所在。
- 避免成为“房间里最聪明的人”，应创造空间让他人参与，并对自己的观点保持适度怀疑。
- 绝大多数“慢”的团队实际上是“错位”的团队，即方向、接口或优先级不明确。
行动与交付
- 完美的追求会阻碍进步，先行动、再完善、再优化。
- “行动导向”比“分析瘫痪”更能带来清晰度，可编辑错误页面，但无法编辑空白页面。
- AI 可以辅助快速迭代和反馈。
清晰度而非技巧性
- 代码需要清晰易懂，以便他人（尤其是在紧急情况下）能够理解和维护。
- 为维护者（包括 2 AM 时的你）而非自己写代码。
谨慎创新
- 创新是有成本的，应谨慎使用“创新代币”。
- 只在有独特价值的地方创新，其他地方应倾向于使用成熟、可靠的技术。
价值的可视化与倡导
- 优秀的成果需要被看见，代码不会替你说话，人会。
- 要让你的影响对他人可见，尤其是在你不在场时。
代码的最小化
- 最“好”的代码是你根本不需要写的代码。
- 在构建之前，思考“如果我们不这样做，会发生什么？”。
兼容性即产品
- 在大规模系统下，即使是 bug 也会成为用户的依赖。
- API 设计实际上是 API 退休设计，需要考虑兼容性、时间和用户体验。
聚焦可控因素
- 在大型组织中，很多变量不可控，应专注于自己的影响范围。
- 保持理智和高效的关键在于聚焦可控之事。
抽象的代价
- 抽象会转移复杂性，而非消除它，当问题发生时，你仍需要理解底层。
- 持续学习“更低级”的知识，以应对抽象失效的情况。
教学即学习
- 写作和教学是促进理解的有效方式，能暴露自己知识的不足。
- 尝试用简单的方式解释事物，是检验和深化理解的捷径。
“粘合剂”工作的价值与可见性
- 文档、入职、跨团队协调等“粘合剂”工作至关重要，但容易被忽视。
- 要将这些工作视为可见的影响，而非仅仅是“乐于助人”。
避免轻易获胜
- 如果总是轻易获胜，可能意味着积累了“沉默的阻力”。
- 真正的对齐需要时间、理解和妥协，而非赢得争论。
度量与目标
- 任何被量化的指标都会被“博弈”。
- 在衡量时，应同时关注速度和质量/风险，并注重趋势分析。
承认未知
- 领导者承认“我不知道”能创造一个更安全的环境，鼓励团队成员也敢于提问。
- 好奇心和承认未知才能促进团队学习。
人脉网络
- 人脉是你最重要的长期资产，远比任何一份工作都持久。
- 以好奇和慷慨的态度建立和维护人脉。
性能提升源于移除
- 许多性能提升来自于移除不必要的工作，而非增加技术复杂度。
- 最快的代码是那些从不运行的代码。
流程的本质
- 良好的流程应简化协调、降低失败成本，而非制造官僚主义。
- 如果流程的价值无法解释，它可能只是负担。
时间价值
- 职业生涯后期，时间成为比金钱更宝贵的资源。
- 有意识地权衡时间和回报，避免过度追求金钱而牺牲宝贵的时间。
复利效应
- 专业技能的提升需要刻意练习和时间积累，没有捷径。
- 将职业生涯视为复利增长，而非购买彩票，持之以恒会带来长远回报。
核心思想
- 保持好奇心、谦逊，并始终记住工作关乎人（用户和团队成员）。
- 工程师的职业生涯足够长，可以从错误中学习，并分享经验。

Refs

使用 ImageMagick 和 libvips 进行服务器端批量图片压缩

Tue, 06 Jan 2026 17:38:00 GMT

前言

最近需要处理别人的服务器上大量历史图片的压缩问题。因为历史遗留原因，public/uploads 下累积了不少高分辨率的全景图和常规照片，占用存储空间越来越大。虽然之前在前端生产环境中一直使用 sharp-cli、@napi-rs/image 等进行图片处理，但这次面对的是已存储的历史图片批量压缩场景，而且这次提供的环境是堡垒机，只能通过网页终端进行操作，没有 GUI，需要更灵活的命令行工具。

这篇文章记录了完整过程，希望对有类似需求的朋友有所帮助。

为什么不用 sharp-cli?

sharp-cli 和 @napi-rs/image 一般是我在生产环境中的首选,性能优异且 API 友好。但这次需求是批量处理已存储的大量图片，而 sharp-cli 更适合集成到构建流程或 Node.js 脚本中。对于这种一次性批量操作，传统的 ImageMagick/libvips 命令行工具更加直接。

工具对比

在压缩之前我看过了这些工具：

工具	优势	劣势	适用场景
ImageMagick	功能全面,文档丰富	大图处理内存占用高	通用图片处理
libvips	流式处理,内存效率极高	功能相对聚焦	超大图片/批量处理
sharp-cli	性能优异,API 友好	需要 Node.js 环境	构建流程集成
Squoosh CLI	支持现代格式(WebP/AVIF)	已停止维护	❌ 不推荐生产使用
guetzli/mozjp	极致压缩(JPEG)	处理速度极慢	追求极限压缩率场景

最终选择：ImageMagick + libvips 组合方案

一开始使用 ImageMagick 处理 10MB 以下的常规图片，很快速很方便，但发现超大图片（100MB+）会爆内存。
libvips 是 sharp 底层使用的库，处理超大全景图（100MB+）绰绰有余。

infographic compare-hierarchy-left-right-circle-node-pill-badge
data
  title 工具选择策略
  items
    - label ImageMagick
      children
        - label 常规图片
          desc <10MB 的图片
        - label 功能全面
          desc 支持各种格式转换
        - label 语法简单
          desc mogrify 一行命令
    - label libvips
      children
        - label 超大图片
          desc 100MB+ 全景图
        - label 内存效率
          desc 流式处理不爆内存
        - label sharp底层
          desc 生产级性能保证

开始前准备

infographic list-row-simple-horizontal-arrow
data
  title 操作流程
  items
    - label 检查容量
      desc 查看磁盘剩余空间
    - label 统计大小
      desc 评估压缩前文件大小
    - label 备份数据
      desc 防止误操作
    - label 执行压缩
      desc 使用合适工具

最重要的两点当然是：

查看原来的所有图片大小
备份你要压缩的图片（因为 mogrify 会在原图的基础上直接进行压缩，所以备份很重要）

# du（disk usage)
# -sh: 只显示每个参数的总大小，以人类可读的格式显示(K, M, G)
# sort -hr: 按大小倒序排列
du -sh * | sort -hr
# 只列出 17 开头的
du -sh 17* | sort -hr

输出如下：

root@3d:/myapp/storage/uploads/panorama/backup# du -sh * | sort -hr
147M    1766019200667-1c2d8x.jpg
130M    1766019053272-aylt0b.jpg
120M    1766019107903-jl2i2s.jpg
63M     1765977415640-hu7yap.jpg
……

然后备份，备份前记得 df -h 查看磁盘剩余可用空间。

df -h
# 可用空间足够，则进行备份
tar -cvf uploads_backup_$(date +%Y%m%d).tar uploads/
# 或者比如说我要备份 17 开头的
tar -czvf backup_17_$(date +%Y%m%d).tar.gz 17*
# 备份所有 17 开头且大于 10M 的文件
tar -czvf backup_17_large_$(date +%Y%m%d).tar.gz $(find . -name "17*" -size +10M)

会把 upload 目录备份为 uploads_backup_20251223.tar 文件

工具安装

然后就到了开始实行压缩的环节

ImageMagick

imagemagick.org

ImageMagick | Command-line Processing

ImageMagick is a powerful open-source software suite for creating, editing, converting, and manipulating images in over 200 formats. Ideal for developers, designers, and researchers.

https://imagemagick.org/script/command-line-processing.php

# Debian/Ubuntu
sudo apt update && sudo apt install imagemagick -y

# macOS
brew install imagemagick

# 验证
magick -version

需要注意的是新版 ImageMagick 7+ 推荐使用 magick 命令，但是服务器上比较老所以我用的旧语法。

libvips

libvips.org

Vips: Using > vipsthumbnail

Reference for Vips-8.0: Using > vipsthumbnail

https://www.libvips.org/API/8.17/using-vipsthumbnail.html

# Debian/Ubuntu
sudo apt install libvips-tools -y

# macOS
brew install vips

# 验证
vipsthumbnail --version

踩坑记录

超大图片内存溢出

处理 150MB 的全景图时遭遇 cache resources exhausted 错误:

# 假设以 change 开头的是我们要批量压缩的图片
# 原图可能有 20000x 以上，可以 resize 到 9000x 以下
mogrify -quality 75 -resize "9000x>" ./change*.jpg

根本原因:

ImageMagick 采用全图加载到内存的处理方式:

对于 150MB 的航拍全景图 JPEG 文件，其实际分辨率可达 23000×11000 左右。解压后的像素数据大小为：

20000 × 10000 × 3 字节 = 600MB（RGB 格式）

ImageMagick 在处理过程中还需要：

创建多个中间缓冲区
存储变换矩阵
保存临时结果

因此实际内存占用可达 900MB-2GB，超出了默认资源限制。（我不确定这里的描述是否准确，但反正那个小水管服务器上是跑不了的）

ImageMagick 处理超大图很吃力，所以我请出了 libvips。

# 1. 先看看有哪些文件
find . -maxdepth 1 -name "17*.jpg" -size +10M -exec ls -lh {} \;

# 2. 备份(安全起见)
tar -czvf backup_17_10M_$(date +%Y%m%d).tar.gz 17*.jpg

# 3. 执行压缩
for f in 17*.jpg; do
  size=$(stat -c%s "$f" 2>/dev/null)
  if [ $size -gt 10485760 ]; then
    echo "Compressing: $f ($(du -h "$f" | cut -f1))"
    vipsthumbnail "$f" -s 9000 -o "temp_[Q=75].jpg"
    if [ -f "temp_.jpg" ]; then
      mv "temp_.jpg" "$f"
      echo "Done: $f → $(du -h "$f" | cut -f1)"
    fi
  fi
done

# 4. 检查结果
du -sh 17*.jpg | sort -hr

注意这里 temp_[Q=75].jpg 中的 [Q=75] 会被替换为空，这是 vipsthumbnail 的文件名替换规则。

在 vipsthumbnail 命令中，-o 参数支持特殊的占位符替换。而 [Q=75] 是一个保存选项占位符，用于指定 JPEG 质量

在最终生成的文件名中，这部分会被移除（替换为空）

大图片压缩圆满完成。

分目录 mogrify 批量压缩

注意 mogrify 会在原图的基础上直接进行压缩，所以备份很重要

较小的图片使用 ImageMagick 的 mogrify 进行就地批量修改:

# 先备份
cp -r . ../backup_before_mogrify/
# 就地修改（mogrify）
mogrify -quality 75 -resize "4000x>" input.jpg
# 或输出到新文件（convert）
convert input.jpg -quality 75 -resize "4000x>" output.jpg

其他常用的 resize 选项:

"4000x>"     # 只缩小,宽度限制4000px
"4000x4000>" # 只缩小,宽高都不超过4000px
"50%"        # 缩小到50%
"4000x3000!" # 强制缩放到指定尺寸(可能变形)

有很多的子目录

root@3d:/myapp/storage/uploads/panorama# du -sh * | sort -hr
131M    cmjpqjihk002mlm01qyyk3vqc
131M    cmjpp9pfk001ulm01dr2aina9
129M    cmjxtmsfs00eilm01iso8kaq2
128M    cmja74wwh00fcl701ie777fnj
127M    cmja751nb00fel701u4oqmgfk
126M    cmk0yw2zx004nlp01i7r22uoe

里面是这种格式的相对小的图片。

root@3d:/myapp/storage/uploads/panorama/cmjpqjihk002mlm01qyyk3vqc# du -sh * | sort -hr
26M     cmjpqjihk002mlm01qyyk3vqc.right.jpg
26M     cmjpqjihk002mlm01qyyk3vqc.left.jpg
25M     cmjpqjihk002mlm01qyyk3vqc.back.jpg
24M     cmjpqjihk002mlm01qyyk3vqc.front.jpg
18M     cmjpqjihk002mlm01qyyk3vqc.bottom.jpg
13M     cmjpqjihk002mlm01qyyk3vqc.top.jpg

那我就直接用 mogrify -quality 75 -resize "4000x>" ./public/uploads/**/*.jpg 了，快一些。

我需要压缩大于 20M 的目录，并且批量先 cd 进目录，处理完再 cd ..，过程中我还想看进度:

先备份大于 20M 的目录

backup_file="../panorama_backup_$(date +%Y%m%d_%H%M%S).tar.gz"
dirs_to_backup=""

for dir in */; do
  size=$(du -sm "$dir" | cut -f1)
  if [ $size -gt 20 ]; then
    echo "加入备份: $dir ($size MB)"
    dirs_to_backup="$dirs_to_backup $dir"
  fi
done

tar -czf "$backup_file" $dirs_to_backup
echo "备份完成: $backup_file"

备忘录

du -sm 中的 -m 参数指定了单位是 MB（megabytes）
-s 是 summarize（汇总）
-m 是 megabytes（兆字节）
cut -f1 提取第一列（数字部分）
tar -czf 创建一个用 gzip 压缩的 tar 归档文件，名字叫 backup.tar.gz
-c = create 创建新的归档文件
-z = gzip 使用 gzip 压缩
-f = file 指定文件

开始压缩，使用 mogrify -quality 75 -resize "4000x>" "$img"（ImageMagick 7+ 推荐使用 magick mogrify 代替旧版的 mogrify）

使用 ImageMagick 压缩和调整图片

mogrify 直接修改原图片（不创建副本）
-quality 75 设置 JPEG 质量为 75%
-resize "4000x>" 如果宽度超过 4000 像素就缩小，保持宽高比，> 表示只缩小不放大

以下命令的大意是：

遍历所有以 cmj 开头的子目录，检查每个目录的大小
筛选大于 20 MB 的目录进行处理（跳过已经压缩过的小目录）
对符合条件的目录：进入目录 -> 统计其中的 JPG 文件数量 -> 逐个处理每张 JPG 图片 -> 降低质量到 75%，如果宽度超过 4000 像素则缩小到 4000 像素（保持宽高比）
显示实时进度（如 [3/10] photo.jpg）
处理完成后返回上级目录，继续处理下一个目录

for dir in cmj*/; do
  size=$(du -sm "$dir" | cut -f1)
  if [ $size -gt 20 ]; then
    echo "处理: $dir ($size MB)"
    cd "$dir"
    total=$(ls *.jpg 2>/dev/null | wc -l)
    count=0
    for img in *.jpg; do
      ((count++))
      echo "  [$count/$total] $img"
      mogrify -quality 75 -resize "4000x>" "$img"
    done
    cd ..
    echo "完成: $dir"
  fi
done

备忘录

wc -l 中的 -l 是 lines（行数），统计行数
((count++)) 是 bash 的算术运算语法，让变量自增 1
mogrify 是 ImageMagick 工具，直接修改原文件而不创建副本
-quality 75 设置 JPEG 压缩质量为 75%（0-100，数值越高质量越好文件越大）
-resize "4000x>" 中的 > 表示”只缩小不放大”，如果图片宽度 ≤4000 则不处理

效果拔群。

写在最后

为什么不直接用 sharp-cli?

sharp 非常优秀,我在生产环境的图片上传流程中一直使用。但对于已存储的历史图片批量压缩,传统命令行工具更灵活:

不需要写 Node.js 脚本
直接用 shell 管道/find 组合
libvips 本身就是 sharp 的底层引擎
下次再用直接改改就可以

如何达到最优的压缩效果？

更细致的压缩质量的话，可以看这篇 Stack Overflow 帖子，很具体地讨论了使用 ImageMagick 压缩 JPEG 图片文件以实现最小文件大小但又不损失过多质量的问题。

https://stackoverflow.com/questions/7261855/best-options-parameters-for-imagemagick-to-compress-jpegs-files-to-the-minimal-s

stackoverflow.com

以下是 AI 辅助总结的该帖子的要点总结

问题

原始提问者（Javis Perez）遇到的问题是：

压缩效果不佳： 使用 ImageMagick 压缩 JPEG 文件时，无法获得显著的文件大小差异。
输出文件反而更大： 在默认情况下，输出的图片文件大小甚至比输入文件更大。
尝试后仍不理想： 即使使用了 +profile "*" 和 -quality 70 选项，输出文件（264KB）仍然接近或略大于输入文件（255KB）。
明确的目标： 希望能将图片压缩到至少 150KB，并寻求实现这一目标的 ImageMagick 选项。

解决方式

帖子中提供了多种解决方案和参数组合，可以归纳为以下几点：

核心参数组合 (最受推荐和高赞的方案)：
- Command: convert -strip -interlace Plane -gaussian-blur 0.05 -quality 85% source.jpg result.jpg
- 参数解释:
  - -quality 85%: 设置 JPEG 压缩质量为 85%（可根据需求调整，通常在 60-85 之间，数字越低文件越小，但质量损失越大）。
  - -strip: 移除图片中的所有元数据（如 EXIF 信息、评论等），这是无损缩小文件大小的有效方法。
  - -interlace Plane (或 -interlace JPEG): 创建渐进式 JPEG，虽然不直接减小文件大小，但能改善图片在网络上的加载体验。
  - -gaussian-blur 0.05: 应用一个非常小的（如 0.05）高斯模糊。这个参数有争议，一些用户认为它能平滑图像中的噪点，从而提高压缩率，显著减小文件大小；另一些用户则认为它会造成图像模糊，不如直接降低-quality。
Google PageSpeed Insights 推荐的优化方案：
- Command: convert image.jpg -sampling-factor 4:2:0 -strip -quality 85 -interlace JPEG -colorspace RGB image_converted.jpg
- 参数解释:
  - -sampling-factor 4:2:0: 这是色彩子采样，将色度通道的采样率减半，同时不影响亮度通道。人眼对亮度变化比色度变化更敏感，因此这种方法能在不明显影响视觉质量的情况下大幅度减小文件大小。
  - -strip 和 -quality 85 及 -interlace JPEG: 同上。
  - -colorspace RGB: 确保图片以正确的 RGB 色彩空间处理。
- 补充选项： -define jpeg:dct-method=float: 使用更精确的浮点离散余弦变换（DCT）而不是默认的快速整数版本，可以在不增加文件大小的情况下略微提高转换的保真度。
直接指定目标文件大小：
- Command: convert image.jpg -define jpeg:extent=150kb result.jpg
- 参数解释:
  - -define jpeg:extent=: 从 ImageMagick v6.5.8-2 开始，可以直接指定 JPEG 输出文件的最大大小（例如 “150kb”）。ImageMagick 会自动调整质量以达到这个目标大小。这是解决原始问题中”压缩到 150kb”最直接的方法，但会带来质量损失。
图像尺寸调整（最显著的减小文件大小的方法）：
- Command (示例): mogrify -quality "97%" -resize 2048x2048 -filter Lanczos -interlace Plane -gaussian-blur 0.05
- 参数解释:
  - -resize WxH 或 -adaptive-resize X%: 调整图像的尺寸。这是减小文件大小最有效的方法之一，尤其是对于高分辨率图片。
  - -filter Lanczos: 一种高质量的缩放滤镜（通常是默认值）。
- 注意： 减小图片尺寸会改变图片的实际像素数据。
其他考量及建议：
- 批处理： 对于多个文件，可以使用mogrify命令替代convert。例如：mogrify -strip -interlace Plane -gaussian-blur 0.05 -quality 85% *.jpg。注意： mogrify会覆盖原文件，操作前务必备份。
- 质量与模糊的权衡： 帖子中多次提及 -gaussian-blur 的争议。许多用户认为简单地降低 -quality 即可达到目的，或者结合 -sampling-factor 4:2:0 更有效，避免引入不必要的模糊。对于大尺寸图片，微小的模糊可能不易察觉；对于小图片，则效果可能不佳。
- 外部工具： 推荐使用如 ImageOptim、pngquant 等外部工具进行进一步的无损或有损优化。
- 重新压缩的副作用： 有评论指出，对已压缩的 JPEG 进行再压缩，即使文件大小增大，也会导致图像质量下降。

Refs

本文随时修订中,有错漏可直接评论

Infographic 信息图指南

Sat, 03 Jan 2026 09:31:00 GMT

本文示例图表由 AI 创作

给博客更新了新功能，可以渲染 Infographic 图表，这里也介绍一下。

Infographic 是蚂蚁集团 AntV 团队推出的新一代声明式信息图表生成与渲染框架，是专为 AI 时代设计的声明式信息图表渲染引擎。

它采用简洁的声明式语法，支持 AI 流式输出与实时渲染，并内置了超过 200 种信息图表模板、组件和布局。

该框架不仅提供高质量的 SVG 输出，还拥有丰富的主题系统（包括手绘风和渐变色）以及配套的在线编辑器和 Skills，极大提升了信息展示的效率。

用下来，感觉比 Mermaid 图表好用。后续还可以改一下主题。

什么是 Infographic

Infographic（信息图）是一种将数据、信息和知识以视觉化方式呈现的图表形式。相比传统的文字描述，信息图能够更直观、更有吸引力地传达信息。

在本博客中，你可以直接在 Markdown 代码块中使用 infographic 标记来创建各种类型的信息图，支持：

列表展示
流程说明
数据对比
层级结构
统计图表
象限分析
关系展示
还有很多其他的模版，参见 Infographic 官方网站的示例

en-us.infographic.antv.vision

Gallery – AntV Infographic

AntV Infographic - A powerful visualization library for building interactive and customizable infographics.

https://infographic.antv.vision/gallery

怎么写的？

官方仓库里现在有 skill，我也集成到我博客中了，只需要让 claude code 根据我文章的信息，使用这些 skill 来创建，非常方便了。

github.com

Infographic/.skills at main · antvis/Infographic

An Infographic Generation and Rendering Framework, bring words to life with AI! - antvis/Infographic

https://github.com/antvis/Infographic/tree/main/.skills

自己写的话，官方也提供了编辑器，还有很多社区贡献的编辑器。

Infographic Gallery 这里有很多示例，另外图标是在 Infographic Icon 这里语义化搜索的。

基本语法

在代码块中使用 infographic 标记，第一行指定模板名称，然后使用类似 YAML 的语法定义数据：

```infographic
infographic <template-name>
data
  title 标题
  desc 描述
  items
    - label 条目名称
      desc 条目描述
      icon icon-name
```

列表类模板 (list-*)

适合展示信息列表、特性清单、技术栈等。

网格卡片布局

使用 list-grid-badge-card 模板展示卡片式列表：

infographic list-grid-badge-card
data
  title 前端技术栈
  desc 现代化前端开发常用技术
  items
    - label TypeScript
      desc 类型安全的 JavaScript 超集
      icon language-typescript
    - label React
      desc 用于构建用户界面的 JavaScript 库
      icon react
    - label Astro
      desc 现代化静态站点生成器
      icon mdi/rocket-launch
    - label Tailwind CSS
      desc 实用优先的 CSS 框架
      icon tailwind
    - label Vite
      desc 下一代前端构建工具
      icon mdi/lightning-bolt
    - label Biome
      desc 一体化的 Web 工具链
      icon biome

糖果风格卡片

使用 list-grid-candy-card-lite 创建更有趣的卡片样式：

infographic list-grid-candy-card-lite
data
  title 博客特色功能
  desc 本博客的特色功能如下
  items
    - label 深色模式
      icon mdi/brightness6
      illus creative-experiment
      desc 优雅的主题切换
      icon mdi/theme-light-dark
    - label 全站搜索
      desc 基于 Pagefind 的无后端搜索
      icon mdi/magnify
    - label Markdown 增强
      desc 支持 GFM、Mermaid、Infographic
      icon mdi/markdown

水平箭头列表

使用 list-row-horizontal-icon-arrow 展示线性列表：

infographic list-row-simple-horizontal-arrow
data
  title 企业优势列表
  desc 展示企业在不同维度上的核心优势与表现值
  items
    - label 品牌影响力
      value 85
      desc 在目标用户群中具备较强认知与信任度
      time 2021
      icon mingcute/diamond-2-fill
      illus creative-experiment
    - label 技术研发力
      value 90
      desc 拥有自研核心系统与持续创新能力
      time 2022
      icon mingcute/code-fill
      illus code-thinking
    - label 市场增长快
      value 78
      desc 近一年用户规模实现快速增长
      time 2023
      icon mingcute/wallet-4-line
      illus business-analytics
    - label 服务满意度
      value 88
      desc 用户对服务体系整体评分较高
      time 2020
      icon mingcute/happy-line
      illus feeling-happy
    - label 数据资产全
      value 92
      desc 构建了完整用户标签与画像体系
      time 2022
      icon mingcute/user-4-line
      illus mobile-photos
    - label 创新能力强
      value 83
      desc 新产品上线频率高于行业平均
      time 2023
      icon mingcute/rocket-line
      illus creativity
theme light
  palette antv

流程/顺序类模板 (sequence-*)

适合展示步骤、流程、时间线等有顺序关系的信息。

之字形步骤

使用 sequence-zigzag-steps-underline-text 展示流程步骤：

infographic sequence-zigzag-steps-underline-text
data
  title 博客搭建流程
  items
    - label 选择框架
      desc 选择 Astro 作为静态站点生成器
    - label 设计主题
      desc 参考 Shoka 主题进行设计
    - label 开发功能
      desc 实现文章系统、搜索、评论等功能
    - label 部署上线
      desc 使用 Vercel 进行自动化部署

圆形流程

使用 sequence-circular-simple 展示循环流程：

infographic sequence-circular-simple
data
  title PDCA 循环
  items
    - label Plan
      desc 制定计划
    - label Do
      desc 执行实施
    - label Check
      desc 检查验证
    - label Act
      desc 改进优化

垂直路线图

使用 sequence-roadmap-vertical-simple 展示时间线或路线图：

infographic sequence-roadmap-vertical-simple
data
  title 项目里程碑
  items
    - label 2024 Q1
      desc 项目启动，完成基础架构
    - label 2024 Q2
      desc 实现核心功能，开始内容迁移
    - label 2024 Q3
      desc 优化性能，添加高级功能
    - label 2024 Q4
      desc 正式发布，持续优化

金字塔结构

使用 sequence-pyramid-simple 展示层级递进关系：

infographic sequence-pyramid-simple
data
  title 马斯洛需求层次
  items
    - label 自我实现
    - label 尊重需求
    - label 社交需求
    - label 安全需求
    - label 生理需求
theme
  palette
    - #8b5cf6
    - #3b82f6
    - #06b6d4
    - #10b981
    - #f59e0b

对比类模板 (compare-*)

适合展示二元对比、优缺点分析等。

水平二元对比

使用 compare-binary-horizontal-simple-fold 进行对比：

infographic compare-binary-horizontal-simple-fold
data
  title SSR vs SSG
  items
    - label 服务端渲染 (SSR)
      children
        - label 实时生成
          desc 每次请求时渲染页面
        - label 动态内容
          desc 适合频繁更新的内容
        - label 服务器负载
          desc 需要服务器资源
    - label 静态生成 (SSG)
      children
        - label 构建时生成
          desc 提前生成所有页面
        - label 静态内容
          desc 适合内容相对稳定的场景
        - label CDN 友好
          desc 可以部署到 CDN 边缘节点

SWOT 分析

使用 compare-swot 进行 SWOT 分析：

infographic compare-swot
data
  title 技术博客 SWOT 分析
  items
    - label 优势 (Strengths)
      children
        - label 技术积累
        - label 个人品牌
        - label 知识沉淀
    - label 劣势 (Weaknesses)
      children
        - label 时间投入
        - label 持续更新压力
        - label 初期流量低
    - label 机会 (Opportunities)
      children
        - label 技术社区活跃
        - label 开源生态发展
        - label 个人成长空间
    - label 威胁 (Threats)
      children
        - label 内容同质化
        - label 平台竞争
        - label 技术快速迭代

层级类模板 (hierarchy-*)

适合展示组织结构、分类体系等树形关系。

系统分层结构

使用 hierarchy-structure 展示多层架构，非常适合展示系统架构、模块分层：

infographic hierarchy-structure
data
  title 系统分层结构
  desc 展示不同层级的模块与功能分组
  items
    - label 展现层
      children
        - label 小程序
        - label APP
        - label PAD
        - label 客户端
        - label WEB
    - label 应用层
      children
        - label 核心模块
          children
            - label 功能1
            - label 功能2
            - label 功能3
            - label 功能4
            - label 功能5
            - label 功能6
        - label 基础模块
          children
            - label 功能1
            - label 功能2
            - label 功能3
            - label 功能4
            - label 功能5
            - label 功能6
        - label 其他模块
          children
            - label 功能1
            - label 功能2
            - label 功能3
            - label 功能4
            - label 功能5
            - label 功能6
    - label 平台层
      children
        - label 模块1
          children
            - label 功能1
            - label 功能2
            - label 功能3
            - label 功能4
        - label 模块2
          children
            - label 功能1
            - label 功能2
            - label 功能3
            - label 功能4
        - label 模块3
          children
            - label 功能1
            - label 功能2
            - label 功能3
            - label 功能4

科技风格树形图

使用 hierarchy-tree-tech-style-capsule-item 展示层级结构：

infographic hierarchy-tree-tech-style-capsule-item
data
  title 前端技术体系
  items
    - label 前端开发
      children
        - label 基础技术
          children
            - label HTML
            - label CSS
            - label JavaScript
        - label 框架/库
          children
            - label React
            - label Vue
            - label Astro
        - label 工程化
          children
            - label Vite
            - label Webpack
            - label Rollup

圆角矩形树形图

使用 hierarchy-tree-curved-line-rounded-rect-node 展示层级：

infographic hierarchy-tree-curved-line-rounded-rect-node
data
  title 博客内容分类
  items
    - label 技术文章
      children
        - label 前端
          children
            - label React
            - label TypeScript
        - label 后端
          children
            - label Node.js
            - label 数据库
    - label 生活随笔
      children
        - label 年度总结
        - label 读书笔记

图表类模板 (chart-*)

适合展示统计数据、数值对比等。

柱状图

使用 chart-column-simple 展示数据对比：

infographic chart-column-simple
data
  title 月度文章发布统计
  items
    - label 1月
      value 5
    - label 2月
      value 8
    - label 3月
      value 12
    - label 4月
      value 6
    - label 5月
      value 10
    - label 6月
      value 15

条形图

使用 chart-bar-plain-text 展示横向对比：

infographic chart-bar-plain-text
data
  title 编程语言使用占比
  items
    - label TypeScript
      value 45
    - label JavaScript
      value 25
    - label Python
      value 15
    - label Go
      value 10
    - label Others
      value 5

饼图

使用 chart-pie-plain-text 展示占比分布：

infographic chart-pie-plain-text
data
  title 访问来源分布
  items
    - label 搜索引擎
      value 45
    - label 社交媒体
      value 30
    - label 直接访问
      value 15
    - label 外部链接
      value 10

环形图

使用 chart-pie-donut-pill-badge 创建环形图：

infographic chart-pie-donut-pill-badge
data
  title 技术栈占比
  items
    - label 前端
      value 50
    - label 后端
      value 30
    - label DevOps
      value 20

折线图

使用 chart-line-plain-text 展示趋势：

infographic chart-line-plain-text
data
  title 博客访问量趋势
  items
    - label 第1周
      value 100
    - label 第2周
      value 150
    - label 第3周
      value 200
    - label 第4周
      value 280
    - label 第5周
      value 350
    - label 第6周
      value 420

象限分析 (quadrant-*)

适合展示四象限分析、优先级矩阵等。

简单卡片象限

使用 quadrant-quarter-simple-card 进行象限分析：

infographic quadrant-quarter-simple-card
data
  title 四象限分析
  items
    - label 重要且紧急
      desc 直接规避风险
      illus notify
    - label 重要不紧急
      desc 采取风险控制措施
      illus coffee
    - label 不重要但紧急
      desc 通过保险转移风险
      illus diary
    - label 不重要不紧急
      desc 选择接受风险
      illus invest

关系图 (relation-*)

适合展示元素间的关联关系。

圆形图标关系

使用 relation-circular-progress 展示关系网络：

infographic relation-circle-circular-progress
data
  title 子公司盈利分析
  desc 各子公司财务表现，盈利同比增长
  items
    - label 云计算子公司
      value 25
      desc 年度净利润率达25%，成为集团核心增长引擎
      icon mingcute/cardano-ada-fill
    - label 人工智能子公司
      value 40
      desc AI业务快速扩张，盈利同比增长40%
      icon mingcute/openai-fill
    - label 物联网子公司
      value 1000
      desc IoT设备出货量突破千万，盈利稳步提升
      icon mingcute/medium-fill
    - label 金融科技子公司
      value 18
      desc 数字支付业务增长迅猛，净利润率18%
      icon mingcute/paypal-fill
    - label 新能源子公司
      value 50
      desc 绿色能源项目实现规模化盈利，增长潜力巨大
      icon mingcute/drone-fill

主题定制

可以通过 theme 块自定义颜色方案：

infographic list-grid-badge-card
data
  title 自定义配色示例
  items
    - label 主色调
      desc 品牌主色
    - label 辅助色
      desc 强调色彩
    - label 中性色
      desc 背景文字
theme
  palette
    - #3b82f6
    - #8b5cf6
    - #f97316
    - #06b6d4
    - #10b981

实用技巧

1. 选择合适的模板

根据要展示的信息类型选择对应的模板：

列表信息 → list-*
流程步骤 → sequence-*
数据对比 → compare-* 或 chart-*
层级关系 → hierarchy-*
优先级分析 → quadrant-*
关联关系 → relation-*

2. 合理使用图标

使用 Material Design Icons 让信息图更生动：

icon mdi/rocket-launch
icon mdi/heart
icon mdi/lightbulb
icon mdi/chart-line

3. 控制信息密度

每个信息图不要包含过多条目（建议 3-8 个）
使用简洁的标签和描述
复杂信息可以拆分成多个信息图

4. 注意主题适配

信息图会自动跟随博客的深色/浅色主题切换，无需额外配置。

总结

Infographic 为 Markdown 文档提供了强大的可视化能力，能够让技术博客、文档、笔记更加生动易读。合理使用各种模板，可以显著提升内容的表现力和可读性。

更多模板和详细文档，请访问 Infographic 官方网站的示例。

FE Bits Vol.21 | 博客圣诞特效与 Moe Copy 更新，AntV 推出 Infographic

Wed, 31 Dec 2025 13:49:00 GMT

本期网址 https://blog.cosine.ren/post/weekly-21 本周刊更新时间期望是在每周天。推荐订阅本周刊的 RSS。公众号前端周周谈 FE Bits，点击阅读原文链接可查看原文。 QQ 讨论小群 598022684，讨论前端技术 & 生活，也可在群里投稿自己的文章，随意加入，比较偏向粉丝群的性质～本周刊文章内容同时也开源在 fe-bits-weekly，欢迎关注。

今天是 2025 年 12 月 31 日，星期三。

元旦放假，周刊停更一期，所以今天更新上周天的。

年终总结在写了在写了，但是今天就不一定写的出来了。

个人项目

这周圣诞节，前端圈都没什么动静，不过正好我做了一堆自己项目的更新。

今天一总结，发现真不少啊。

发了一篇博客「Worktrunk 完全指南：让 Git Worktree 和 Claude Code 和平共处」因为我非常喜欢这个工具于是写了一篇博文卖安利～

博客项目

首先是博客的一些更新

LQIP

一开始想在博客中，实现类似 Minimal CSS-only blurry image placeholders 的 CSS-only LQIP（低质量图片占位符），使用单个 CSS 自定义属性 —lqip 编码图片的模糊预览。

这篇文章的技术原理是使用 20 位整数编码图片信息（8 位 Oklab 基础色 + 12 位亮度分量），在 CSS 中通过位运算解码（mod(), round(down), pow() 等），使用径向渐变叠加渲染模糊效果，配合二次缓动实现平滑过渡。

我选择简化一些的实现，不追求 CSS Only 了，因为打算先做博客内部的图片，文章内部的外部图片等后续优化的时候再一起做，放上最终效果在这里：

需要运行一下 nr generate:lqips 就会生成一个 lqips.json 的 json 文件在 assets 下，若没有这个文件则不提供占位符～

blog.cosine.ren

在 Astro 博客中实现 LQIP（低质量图片占位符） | 笔记 / 前端 | 余弦の博客

本文由 AI 辅助写作，作记录用一开始想在博客中，实现类似 Minimal CSS-only blurry image placeholders 的 CSS-only LQIP（低质量图片占位符），使用单个 CSS 自定义属性 --lqip 编码图片的模糊预览。这篇文章的技术原理是使用 20…

https://blog.cosine.ren/post/astro-lqip-implementation

后续看到有人提出更好的实现，已加入 TODO！

圣诞特效

究～极～花里胡哨！！圣诞节到了，想给博客加点节日氛围。最终实现了一套可开关的圣诞特效模块，包括雪花和彩灯以及圣诞配色方案～

雪花效果是从 Shadertoy 上的 Just snow 学来的！彩灯是参考 Toby J 的 CodePen 实现，优化调整了性能，调整为圣诞配色（红、绿、金）

我知道肯定会有人说花里胡哨所以我加了开关，欢迎品鉴～

blog.cosine.ren

为 Astro 博客添加可插拔的圣诞特效模块 | 笔记 / 前端 | 余弦の博客

本文由 AI 辅助写作，作记录用圣诞节到了，想给博客加点节日氛围。最终实现了一套可插拔的圣诞特效模块，包括： 3D 雪花飘落（React Three Fiber + GLSL 着色器）悬挂彩灯装饰（CSS 动画）头像圣诞帽（SVG）圣诞配色方案（CSS 变量）可拖拽圣诞球开关…

https://blog.cosine.ren/post/astro-christmas-effects

如果嫌弃干扰阅读了，可以点击开关关掉～

注意看这个雪是双层的，内容容器夹在雪花中间，远景雪花在文章后面飘过，近景雪花在前面飘过，配合视差效果，感觉还挺满意的。

上面的雪花特效是最初的版本，现在的版本是后来又做了一些优化。

使用指南和反馈

把博客的使用指南先简单搓出来了，然后换了一下切换昼夜模式的过渡动画，从左往右扫过去的感觉。虽然说现阶段还不建议使用，但如果想 fork 出去改改还是都可以的，预计元旦假期我会重点进行重构和性能优化、然后开放一个清理后的仓库方便部署，到那个时候就可以玩耍了！

然后发现 alma 的反馈页面看起来很棒，看了下是用的 featurebase.app 于是我也想试试这个，给博客主题做了一个反馈页面（有没有人用再说吧）：

cos.featurebase.app

Feedback - astro-koharu

Give astro-koharu feedback on how they could improve their product.

https://cos.featurebase.app/

Moe Copy AI 插件更新

Moe Copy AI 插件也大改版了，然后收到了好朋友的 PR！发布了 v0.2.0，变得越来越好用了

github.com

Release v0.2.0 · yusixian/moe-copy-ai

[v0.2.0] - 2025-12-31 Chrome 商店：https://chromewebstore.google.com/detail/moe-copy-ai/dfmlcfckmfgabpgbaobgapdfmjiihnck Release Notes 新功能侧边栏 (Side Panel) - 全新的扩展侧边栏界面，提供更高效的工作流程分段式标签导航，在批量抓取和内容…

https://github.com/yusixian/moe-copy-ai/releases/tag/0.2.0

PR 在原本的直接 fetch 的基础上，提供了「后台打开新 tab」和在「当前页面跳转」来获取下一页按钮选择器改用 XPath，还新增了自动翻页功能，支持跨页批量抓取，感谢 @hyoban 贡献的这个PR #15。

欢迎使用！欢迎反馈！文档在这里。

chromewebstore.google.com

Moe Copy AI - Chrome Web Store

✨ 萌萌哒的 AI 网页数据提取助手 ✨

https://chromewebstore.google.com/detail/moe-copy-ai/dfmlcfckmfgabpgbaobgapdfmjiihnck

github.com

GitHub - yusixian/moe-copy-ai: ✨ 萌萌哒的 AI 网页数据提取助手 ✨

✨ 萌萌哒的 AI 网页数据提取助手 ✨. Contribute to yusixian/moe-copy-ai development by creating an account on GitHub.

https://github.com/yusixian/moe-copy-ai

文章与社区动态

antvis/Infographic：蚂蚁集团 AntV 团队推出新一代声明式信息图表（Infographic）生成与渲染框架，旨在通过 AI 驱动让数据叙事更简单。
How I use AI agents to write code：好文，我也是这样转变的（？）或者说没有转变。有趣的是 AI 出来之后我觉得编码热情或者说想构建产品的欲望越来越强烈了。
Frontend Wrapped 2025: The 10 storylines that defined the year - LogRocket Blog：2025 年前端世界发生了不少大事，这篇文章盘点了那些塑造了这一年的十大热点。
Ever wanted to have a rotating rainbow segments border：介绍并对比了使用 CSS conic-gradient() 与 SVG <rect> 两种技术实现旋转彩虹分段边框的方法。
require(esm) in Node.js: implementer’s tales：Node.js 核心贡献者 Joyee Cheung 深入解析 require(esm) 功能实现过程中遇到的关键挑战与解决方案。

CSS 新特性

补全不足，CSS 锚点定位支持锚定容器回退检测了：Chrome 143+ 引入 CSS 锚点定位回退检测机制，可自动检测容器布局变化并动态切换定位方向，解决传统锚点定位在空间受限时的显示异常问题。
今日学习 CSS style()样式查询及其 range 范围语法：介绍了 CSS @container 的样式查询 (Style Query) 新能力，展示从变量匹配到范围语法 (Range Syntax)、再到针对自身元素匹配的进阶使用技巧。

text-decoration-inset

MDN：text-decoration-inset
兼容性：实验性，文中仅提到 Firefox 146+ 下有效。
介绍文章：text-decoration-inset is Like Padding for Text Decorations

See the Pen VYaPVgr by mrdanielschwarz (@mrdanielschwarz) on CodePen.

CSS 中的 text-decoration-inset 允许开发者像设置内边距一样裁剪文字装饰（如下划线）的左右边缘，从而实现文字装饰与文字内容的精确对齐。该属性支持 em 等相对单位，使装饰能随字体大小缩放，并且可以配合动画和过渡效果，创造出更多原生的、引人注目的文字装饰动态效果。

工具

BentoPDF: 功能强大、注重隐私的开源 PDF 工具集，可自部署，提供超过 50 种 PDF 操作工具，覆盖编辑、转换、安全、优化等多个维度。

Codepen 精选

CSS-Only Stacking Cards

使用 CSS Scroll-Timeline 实现的卡片堆叠，无需 JavaScript：

See the Pen YPWXqmx by karabharat (@karabharat) on CodePen.

easy rainbow segments card border cases

See the Pen RNRPEqb by thebabydino (@thebabydino) on CodePen.

文章：Ever wanted to have a rotating rainbow segments border

实现一个由等分彩虹色段组成的旋转边框效果。作者指出当容器的宽高比远离正方形时，单纯使用 CSS 的 conic-gradient() 方法无法保持色段等分，且分隔线难以垂直于边框。因此，文章提出了更优的解决方案：使用 SVG 的元素来精确控制每个色段的形状和动画，从而获得更稳定、更完美的视觉效果。

Worktrunk 完全指南：让 Git Worktree 和 Claude Code 和平共处

Wed, 31 Dec 2025 12:10:00 GMT

写在前面

最近用 Claude Code 写代码的频率越来越高，有时候会同时开三四个任务：一个在修 bug，一个在加新功能，一个在 review 中，还有一个在跑测试验证新点子。问题来了：它们都需要独立的工作目录，不然会互相串代码。

Git 的 worktree 功能本来就是为这种场景设计的，但原生命令实在有些啰嗦。传统创建一个新 worktree 要这样：

git worktree add -b feature-auth ../myproject-feature-auth
cd ../myproject-feature-auth

删掉它又得回到主目录：

cd ../myproject
git worktree remove ../myproject-feature-auth
git branch -d feature-auth

分支名要输三次，每次都要手动 cd。干这事儿多了，会觉得有些浪费生命，这也是我之前为什么不喜欢 worktree。

直到发现 Worktrunk，才发现 worktree 管理原来可以这么优雅（当然还有很多别的工具）。

用下来感觉非常好，写一篇博客卖一卖安利。

Worktrunk 是什么

简单来说，Worktrunk 是一个 Git Worktree 的 CLI 包装工具，专门为并行运行多个 AI Agent 的场景优化。它的核心理念是：

每个 worktree 对应一个分支，用分支名管理 worktree，路径自动生成。

对比一下命令差异就能感受到差异：

任务	Worktrunk	原生 Git
切换到某个 worktree	`wt switch feat`	`cd ../repo.feat`
创建 worktree + 启动 Claude	`wt switch -c -x claude feat`	`git worktree add -b feat ../repo.feat && cd ../repo.feat && claude`
清理当前 worktree	`wt remove`	`cd ../repo && git worktree remove ../repo.feat && git branch -d feat`
列出所有 worktree 状态	`wt list`	`git worktree list` (只显示路径)

基本就是把 git worktree 的操作复杂度从「记三个参数」降到「说个分支名」。

为什么需要 Worktrunk?

如果你只是偶尔用一下 worktree，原生命令当然就行了。但当你需要频繁并行开发（比如同时跑多个 AI Agent）或者需要自动化流程（创建 worktree 后自动装依赖、跑测试）的时候，Worktrunk 能省下不少时间和心智负担。它本质上是把「用 worktree 的正确姿势」固化成了工具。

安装与配置

安装

macOS/Linux (推荐 Homebrew)：

brew install max-sixty/worktrunk/wt

或者用 Cargo：

cargo install worktrunk

Shell 集成

装完之后必须跑这一步，否则 wt switch 无法切换目录：

wt config shell install

它会在你的 .zshrc 或 .bashrc 里加一段函数，让 wt 命令可以改变当前 shell 的工作目录。

装完重启终端，跑 wt --version 确认安装成功。

核心命令详解

`wt switch` - 切换/创建 Worktree

wt switch | Worktrunk

这是最常用的命令，用法极简：

# 切换到已存在的 worktree (分支名 feat)
wt switch feat

# 基于主分支 main 创建新 worktree + 分支 feat
wt switch -c feat

# 创建 worktree + 自动启动 Claude Code
wt switch -c feat -x claude

# 基于 dev 分支创建新 worktree + 分支 feat-new (而不是 main) + 自动启动 claude
wt switch -c feat-new -b dev -x claude

路径规则： Worktrunk 会自动在主仓库的同级目录下创建 worktree，命名格式是 <repo>.<branch>。比如主仓库在 ~/code/myproject，分支 feat 的 worktree 就在 ~/code/myproject.feat。

参数说明：

-c / --create：创建新 worktree + 分支
-x <cmd>：切换后自动执行命令 (比如 claude, code, npm install)
-b <base>：指定基础分支 (默认是 main)

Shortcut	含义
`^`	默认分支（main/master）
`@`	当前分支/工作树
`-`	之前的工作目录（例如 `cd -` ）

wt switch -                      # Back to previous
wt switch ^                      # Default branch worktree
wt switch --create fix --base=@  # Branch from current HEAD

实战场景

假设你在跑三个并行任务：

# Terminal 1: 修复认证 bug
wt switch -c -x claude fix-auth

# Terminal 2: 重构 API
wt switch -c -x claude refactor-api

# Terminal 3: 加新功能
wt switch -c -x claude feat-dashboard

每个 Claude 实例跑在独立目录里，互不干扰。

`wt list` - 查看所有 Worktree

wt list | Worktrunk

wt list

输出大概长这样:

wt list
  Branch       Status        HEAD±    main↕  Remote⇅  Commit    Age   Message
@ feature-api  +   ↕⇡     +54   -5   ↑4  ↓1   ⇡3      ec97decc  30m   Add API tests
^ main             ^⇅                         ⇡1  ⇣1  6088adb3  4d    Merge fix-auth: hardened to…
+ fix-auth         ↕|                ↑2  ↓1     |     127407de  5h    Add secure token storage

○ Showing 3 worktrees, 1 with changes, 2 ahead, 1 column hidden

比原生 git worktree list 强很多，可以看到很多信息

Git 状态：有多少未提交/未追踪文件
CI 状态：如果配置了 GitHub Actions,会显示最新的构建状态

对于管理多个 worktree 来说,这个视图非常实用。

`wt remove` - 清理 Worktree

wt remove | Worktrunk

# 删除当前 worktree + 分支
wt remove

# 删除指定 worktree
wt remove feature-branch
wt remove old-feature another-branch

# 删除 worktree 但保留分支
wt remove --no-delete-branch feature-branch

# 强制删除未合并的分支
wt remove -D experimental

`wt merge` - 合并工作流

wt merge | Worktrunk

这个命令封装了「合并 → 清理」的完整流程：

# 把当前 worktree 合并到默认分支 如 main
wt merge
# 把当前 worktree 合并到 dev 分支
wt merge dev
# 合并后保留工作树
wt merge --no-remove
# 保留提交历史（不合并）
wt merge --no-squash
# 跳过提交/合并（除非使用 --no-rebase 参数，否则 rebase 仍会运行）
wt merge --no-commit

如果配置了 pre-merge hook，会在合并前自动跑测试或 lint。

`wt select` - 交互式选择器

wt select | Worktrunk

如果你记不清 worktree 名字,可以用 select 命令:

wt select

会弹出一个 fzf 风格的界面,用方向键选择要切换的 worktree。

Hooks

wt hook | Worktrunk

Worktrunk 支持在 worktree 生命周期的不同阶段执行命令，同时支持全局用户 hook 配置（~/.config/worktrunk/config.toml ）和项目 hook 配置（ .config/wt.toml）好的,我只给你补充 Hook 系统这一段内容:

Hook 类型一览

Hook	触发时机	阻塞模式	失败即停
`post-create`	worktree 创建后	是	否
`post-start`	worktree 创建后	否(后台)	否
`post-switch`	每次切换后	否(后台)	否
`pre-commit`	merge 时提交前	是	是
`pre-merge`	合并到目标分支前	是	是
`post-merge`	合并成功后	是	否
`pre-remove`	worktree 删除前	是	是

阻塞模式: 命令执行完成前,主流程会等待
失败即停: 第一个失败的命令会中止整个操作

核心 Hooks 说明

post-create - worktree 创建后立即执行,会阻塞直到完成:

[post-create]
install = "npm ci"                    # 安装依赖
migrate = "npm run db:migrate"        # 数据库迁移
env = "cp .env.example .env"          # 复制环境配置

post-start - worktree 创建后在后台执行,不阻塞切换:

[post-start]
build = "npm run build"               # 构建项目
server = "npm run dev"                # 启动开发服务器

日志输出到 .git/wt-logs/{branch}-{source}-post-start-{name}.log

post-switch - 每次 wt switch 后在后台执行(无论是新建、切换还是切到当前):

post-switch = "echo 'Switched to {{ branch }}'"

pre-commit - merge 时提交前执行,失败即停:

[pre-commit]
format = "cargo fmt -- --check"       # 代码格式检查
lint = "cargo clippy -- -D warnings"  # Lint 检查

pre-merge - 合并到目标分支前执行,失败即停:

[pre-merge]
test = "cargo test"                   # 运行测试
build = "cargo build --release"       # 生产构建

post-merge - 合并成功后在目标分支的 worktree 执行(如果存在),否则在主 worktree 执行:

post-merge = "cargo install --path ."

pre-remove - worktree 删除前执行,失败即停:

[pre-remove]
cleanup = "rm -rf /tmp/cache/{{ branch }}"

模板变量

Hook 命令支持模板变量,运行时自动展开:

变量	示例	说明
`{{ repo }}`	my-project	仓库名
`{{ branch }}`	feature-foo	分支名
`{{ worktree }}`	/path/to/worktree	worktree 绝对路径
`{{ worktree_name }}`	my-project.feature-foo	worktree 目录名
`{{ repo_root }}`	/path/to/main	主仓库根路径
`{{ default_branch }}`	main	默认分支名
`{{ commit }}`	a1b2c3d4e5f6…	HEAD 完整 SHA
`{{ short_commit }}`	a1b2c3d	HEAD 短 SHA
`{{ remote }}`	origin	主远程名称
`{{ remote_url }}`	git@github.com /repo.git	远程 URL
`{{ upstream }}`	origin/feature	上游跟踪分支
`{{ target }}`	main	目标分支(仅 merge hooks)

安全机制

项目 hook(.config/wt.toml)首次运行需要用户批准:

▲ repo needs approval to execute 3 commands:
○ post-create install:
  echo 'Installing dependencies...'
❯ Allow and remember? [y/N]

批准记录保存在用户配置中
命令变更需要重新批准
--yes 跳过提示(适用于 CI)
--no-verify 完全跳过 hooks

管理批准记录:

wt hook approvals add      # 预批准当前项目所有命令
wt hook approvals clear    # 清除当前项目批准
wt hook approvals clear --global  # 清除全局批准

用户级 Hooks

在 ~/.config/worktrunk/config.toml 中配置的 hook 会对所有仓库生效,且不需要批准:

维度	项目 hook	用户 hook
配置位置	`.config/wt.toml`	`~/.config/worktrunk/config.toml`
作用范围	单个仓库	所有仓库
需要批准	是	否
执行顺序	后执行	先执行

我觉得看下来，这个 hook 非常重要，可以复用主 worktree 的缓存:

[post-create]
# 软链接 node_modules 避免重复安装
cache = "ln -sf {{ repo_root }}/node_modules node_modules"
env = "cp {{ repo_root }}/.env.local .env"

独立运行 Hooks

除了自动触发,也可以手动运行 hook 进行测试或重试:

wt hook pre-merge           # 运行 pre-merge hooks
wt hook pre-merge --yes     # 跳过批准提示(适用于 CI)
wt hook show                # 查看所有已配置的 hooks

适用场景: Hook 开发测试、CI 流水线、失败后重试等。

Claude Code 插件监测状态

claude plugin marketplace add max-sixty/worktrunk
claude plugin install worktrunk@worktrunk

手动设置状态标记

除了自动追踪 Claude 状态,你也可以手动给 worktree 设置任何标记，用于其他工作流：

# 给当前分支设置标记
wt config state marker set ""

# 给指定分支设置标记
wt config state marker set "✅" --branch feature

# 直接操作 Git Config (高级用法)
git config worktrunk.state.feature.marker '{"marker":"","set_at":0}'

Statusline 状态栏

wt list statusline --claude-code 可以输出一行紧凑的状态信息,用于 Claude Code 的状态栏显示:

~/w/myproject.feature-auth ! @+42 -8 ↑3 ⇡1 ● | Opus

LLM Commit Messages 自动生成提交信息

LLM Commit Messages | Worktrunk

Worktrunk 可以调用 LLM 自动生成 commit message，集成在 wt merge、wt step commit、wt step squash 等命令中。

不配置也能用，默认会基于文件名生成简单的 message，但配置 LLM 后能生成更有意义的提交信息。

安装与配置

1. 安装 llm 工具

使用的是 llm：

uv tool install -U llm
# 或者直接 brew
brew install llm

2. 配置 API Key

选择你喜欢的 LLM 提供商：

# 使用 Claude (推荐)
llm install llm-anthropic
llm keys set anthropic
# 输入你的 Anthropic API Key

# 或者使用 OpenAI
llm keys set openai
# 输入你的 OpenAI API Key

3. 配置 Worktrunk

创建配置文件（如果还没有）：

wt config create

编辑 ~/.config/worktrunk/config.toml，添加：

[commit-generation]
command = "llm"
args = ["-m", "claude-3-5-haiku-latest"]  # 或 gpt-4o-mini

使用场景

配置完成后，以下命令会自动生成 commit message：

场景 1: 合并分支时生成 squash commit

$ wt merge
◎ Squashing 3 commits into a single commit (5 files, +48)...
◎ Generating squash commit message...
   feat(auth): Implement JWT authentication system

   - Add JWT token generation and validation
   - Implement refresh token mechanism
   - Add middleware for protected routes

场景 2: 提交当前变更

$ wt step commit
◎ Generating commit message...
   fix(api): Handle null response in user endpoint

场景 3: 把多个 commit 压缩成一个

$ wt step squash
◎ Squashing 5 commits...
◎ Generating squash commit message...
   refactor(ui): Modernize component architecture

使用其他 AI 工具

除了 llm，任何能从 stdin 读取提示词并输出文本的工具都行：

# 使用 aichat
[commit-generation]
command = "aichat"
args = ["-m", "claude:claude-3-5-haiku-latest"]

# 使用自定义脚本
[commit-generation]
command = "./scripts/generate-commit.sh"

Fallback 行为

如果没配置 LLM，Worktrunk 会生成基于文件名的简单 message：

Changes to auth.rs & config.rs

CI 状态集成

如果你用 GitHub Actions,Worktrunk 可以在 wt list 里显示构建状态:

# 配置 GitHub Token
wt config github.token "ghp_xxxxxxxxxxxx"

# 之后 wt list 就会显示 CI 状态
wt list

实战工作流

并行跑多个 Claude Code

假设你在用 Zellij 或 Tmux 管理多个终端窗口:

# Pane 1: 修 bug
wt switch -c -x claude fix-login-bug

# Pane 2: 重构
wt switch -c -x claude refactor-utils

# Pane 3: 新功能
wt switch -c -x claude feat-export

每个 Claude 在独立目录里工作,你可以随时切回主目录看全局状态:

wt switch main
wt list

临时验证想法

有时候你想快速验证一个想法,但不想污染当前分支:

# 创建临时 worktree
wt switch -c -x code experiment

# 验证完毕,直接删掉
wt remove

因为 worktree 是独立目录,删掉不会影响其他分支。

Review PR 时跑代码

有 PR 来了,你想在本地跑一下代码:

# 基于 PR 分支创建 worktree
wt switch -c review-pr-123 -b origin/pr-123

# 装依赖、跑测试
npm install
npm run test

# Review 完毕,清理
wt remove

参考资料

Worktrunk 官网
Anthropic - Claude Code Best Practices (官方推荐的 worktree 工作流)
incident.io - Shipping faster with Claude Code and Git Worktrees
Git Worktree 官方文档

astro-koharu 使用指南

Mon, 29 Dec 2025 13:55:00 GMT

一份完整的 astro-koharu 博客系统使用指南，帮助你快速上手并充分利用所有功能特性。

github.com

GitHub - cosZone/astro-koharu: astro-koharu 是一个萌系/二次元/粉蓝配色的 astro 主题博客，灵感来自 Hexo 的 Shoka 主题，加了很多自己的小巧思，性能优越。

astro-koharu 是一个萌系/二次元/粉蓝配色的 astro 主题博客，灵感来自 Hexo 的 Shoka 主题，加了很多自己的小巧思，性能优越。 - cosZone/astro-koharu

https://github.com/cosZone/astro-koharu

快速开始

项目简介

astro-koharu 是一个基于 Astro 5.x 构建的现代化博客系统，从 Hexo 迁移而来，设计灵感和初衷都来自 Shoka 主题。欢迎 fork 出来制作自己的主题。

核心特点：

基于 Astro 5.x，静态站点生成，性能优异
优雅的深色/浅色主题切换
基于 Pagefind 的无后端全站搜索
完整的 Markdown 增强功能（GFM、代码高亮、自动目录）
灵活的多级分类与标签系统（从 Shoka 主题迁移，后续会考虑将其改为可关闭的）
多系列文章支持（周刊、书摘等自定义系列，支持自定义 URL slug）
响应式设计
草稿与置顶功能
阅读进度条与阅读时间估算
移动端文章阅读头部
友链系统与归档页面
多语言支持（i18n）
RSS 订阅支持
LQIP（低质量图片占位符）
圣诞特辑（可开关）

本地开发

# 克隆项目
git clone https://github.com/cosZone/astro-koharu.git
cd astro-koharu

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

# 构建生产版本
pnpm build

# 预览生产构建
pnpm preview

快速部署

使用 Vercel 进行一键部署：

基本配置

站点配置

编辑 config/site.yaml 文件配置站点基本信息：

# =============================================================================
# 站点基础信息
# =============================================================================
site:
  title: 余弦の博客 # 网站标题
  alternate: cosine # 英文短名（用作 logo 文本）
  subtitle: WA 的一声就哭了 # 副标题
  name: cos # 站点作者简称
  description: FE / ACG / 手工 / 深色模式强迫症 / INFP # 站点简介
  avatar: /img/avatar.webp # 头像路径
  showLogo: true # 是否显示 logo
  author: cos # 文章作者
  url: https://blog.cosine.ren/ # 站点域名
  startYear: 2020 # 站点创建年份
  keywords: # SEO 关键词
    - cos
    - cosine
    - 博客
    - 技术
    - 前端

本地轻 CMS 应用

本项目提供独立的 CMS 管理应用，支持文章管理、浏览器内编辑、Markdown 预览等功能。

启动 CMS：

# 首次使用需安装依赖
pnpm cms:install

# 启动 CMS（默认端口 4322）
pnpm cms

CMS 提供以下功能：

文章仪表盘：查看文章统计、分类分布、最近更新
浏览器内编辑器：基于 BlockNote 的富文本编辑，支持 Markdown
草稿/发布切换：一键切换文章状态
置顶管理：快速置顶/取消置顶文章
➕ 新建文章：交互式创建文章，自动生成 frontmatter

本地编辑器跳转

文章页的编辑按钮支持一键跳转到本地编辑器（VS Code / Cursor / Zed 等）。

配置文件： config/site.yaml 的 dev 部分

dev:
  localProjectPath: "/Users/yourname/path/to/astro-koharu" # 本地项目绝对路径
  contentRelativePath: "src/content/blog" # 博客内容目录
  editors:
    - id: vscode
      name: VS Code
      icon: devicon-plain:vscode # 可从 https://icon-sets.iconify.design/ 搜寻图标
      urlTemplate: "vscode://file{path}"
    - id: cursor
      name: Cursor
      icon: simple-icons:cursor
      urlTemplate: "cursor://file{path}"
    - id: zed
      name: Zed
      icon: simple-icons:zedindustries
      urlTemplate: "zed://file{path}"

配置说明：

localProjectPath 必须是本机的绝对路径，否则无法生成正确的文件路径
urlTemplate 支持占位符，会被替换为文件的完整路径
配置后，文章页会显示编辑按钮，点击可直接在本地编辑器中打开文件

特色分类配置：

在首页底部展示的精选分类卡片：

featuredCategories:
  - link: life # 分类链接（对应 category_map）
    label: 随笔 # 显示名称
    image: /img/cover/2.webp # 封面图片
    description: 生活记录、年度总结等 # 描述
  - link: note/front-end
    label: 前端笔记
    image: /img/cover/1.webp
    description: 前端相关的笔记
  # ... 更多分类

多系列文章配置：

配置特色系列（如周刊、书摘等），支持多个系列，每个系列拥有独立页面和自定义 URL：

featuredSeries:
  - slug: weekly # URL 路径: /weekly（必填，作为页面路由）
    categoryName: 周刊 # 分类名称（用于匹配文章）
    label: FE Bits # 显示标签
    fullName: FE Bits 前端周周谈 # 完整名称
    description: | # 描述（支持多行）
      之前在自己的频道进行一些输出，于是有了这个周刊！
      更新时间期望是在每周天
    cover: /img/weekly_header.webp # 封面图
    enabled: true # 是否启用
    icon: ri:newspaper-line # 导航图标（可选）
    highlightOnHome: true # 是否在首页高亮最新文章（可选，默认 true）
    links: # 相关链接
      github: https://github.com/your-username/your-repo
      rss: /rss.xml

  - slug: reading # URL 路径: /reading
    categoryName: 书摘
    label: 读书笔记
    fullName: 我的读书笔记
    description: 读书摘录与感悟
    cover: /img/reading_header.webp
    enabled: true
    highlightOnHome: false # 此系列不在首页高亮

字段说明：

字段	必填	说明
`slug`	✅	URL 路径，如 `weekly` 对应 `/weekly`
`categoryName`	✅	分类名称，用于匹配文章
`label`	❌	显示标签（默认使用 categoryName）
`enabled`	❌	是否启用此系列（默认 true）
`fullName`	❌	完整名称（用于页面标题）
`description`	❌	系列描述
`cover`	❌	封面图片路径
`icon`	❌	导航图标（Iconify 格式）
`highlightOnHome`	❌	是否在首页高亮最新文章（默认 true）
`links`	❌	相关链接（github、rss 等）

社交媒体配置

在 config/site.yaml 中配置社交媒体链接：

social:
  github:
    url: https://github.com/your-username
    icon: ri:github-fill # Iconify 图标名
    color: "#191717" # 主题色
  bilibili:
    url: https://space.bilibili.com/your-uid
    icon: ri:bilibili-fill
    color: "#da708a"
  email:
    url: mailto:your@email.com
    icon: ri:mail-line
    color: "#55acd5"
  rss:
    url: /rss.xml
    icon: ri:rss-line
    color: "#ff6600"
  # ... 更多平台

支持的平台：GitHub, Twitter, Bilibili, 网易云音乐, Email, RSS 等。完整配置请参考 config/site.yaml 文件。

导航配置

在 config/site.yaml 中自定义导航菜单：

navigation:
  - name: 首页
    path: /
    icon: fa6-solid:house-chimney
  - name: 周刊
    path: /weekly # 对应 featuredSeries 中 slug: weekly 的系列
    icon: ri:newspaper-line
  - name: 读书笔记
    path: /reading # 对应 featuredSeries 中 slug: reading 的系列
    icon: ri:book-open-line
  - name: 文章
    icon: ri:quill-pen-ai-fill
    children: # 支持嵌套子菜单
      - name: 分类
        path: /categories
        icon: ri:grid-fill
      - name: 标签
        path: /tags
        icon: fa6-solid:tags
      - name: 归档
        path: /archives
        icon: ri:archive-2-fill
  - name: 友链
    path: /friends
    icon: ri:links-line
  - name: 关于
    path: /about
    icon: fa6-regular:circle-user

注意：系列页面的路径格式为 /{slug}，需要与 featuredSeries 中配置的 slug 字段一致。

分类映射配置

在 config/site.yaml 中配置中文分类名到 URL slug 的映射：

# =============================================================================
# Category Map
# Maps Chinese category names to URL-friendly English slugs
# =============================================================================
categoryMap:
  # Primary categories
  随笔: life
  笔记: note
  工具: tools
  周刊: weekly # 用于分类页面 /categories/weekly
  书摘: reading # 用于分类页面 /categories/reading
  # Secondary categories (for nested paths)
  前端: front-end
  # Add more as needed:
  # 后端: back-end
  # 算法: algorithm

这样，"随笔" 分类的 URL 会是 /categories/life，而不是 /categories/随笔。

注意：categoryMap 仅用于分类页面（/categories/*）的 URL 映射。系列页面的 URL（如 /weekly、/reading）由 featuredSeries 中的 slug 字段单独配置。

文章系统

创建文章

方式一：使用 Koharu CLI（推荐）

使用交互式 CLI 工具快速创建文章：

pnpm koharu new post

CLI 工具会引导你输入标题、分类、标签等信息，自动生成 frontmatter 和 markdown 文件。

方式二：手动创建

在 src/content/blog/ 目录下创建 Markdown 文件。目录结构会影响文章的分类：

src/content/blog/
├── life/              # 随笔分类
│   └── 2024-life-review.md
├── note/
│   ├── front-end/     # 笔记 > 前端
│   │   └── react/
│   │       └── React学习小记.md
│   └── algorithm/     # 笔记 > 算法
│       └── 动态规划学习笔记.md
└── tools/             # 工具分类
    └── vscode插件推荐.md

Frontmatter 字段说明

每篇文章开头需要包含 YAML frontmatter：

必填字段：

---
title: 文章标题 # 必填
date: 2024-12-06 # 必填，发布日期
---

常用可选字段：

---
title: 文章标题
date: 2024-12-06
updated: 2024-12-15 # 最近更新时间（可选，存在时会在文章页显示）
description: 文章摘要描述 # 用于 SEO 和列表展示，如不填写会自动使用 AI 摘要或提取正文前 150 字
link: custom-url-slug # 自定义 URL（默认使用文件名）
cover: /img/cover/1.webp # 封面图片
tags: # 标签列表
  - JavaScript
  - React
categories: # 分类（见下方详细说明）
  - 笔记
subtitle: 副标题 # 文章副标题
catalog: true # 是否显示目录（默认 true）
tocNumbering: true # 是否显示目录编号（默认 true）
draft: false # 是否为草稿（默认 false）
sticky: false # 是否置顶（默认 false）
excludeFromSummary: false # 是否排除 AI 摘要和相似度计算（默认 false，系列文章建议设为 true）
math: false # 是否启用数学公式渲染（默认 false，启用后支持 KaTeX）
quiz: false # 是否启用练习题交互（默认 false，启用后支持四种题型）
password: mySecret # 整篇文章加密密码（可选，设置后整篇文章需输入密码才能阅读）
---

关于 description 字段：

文章描述的优先级：手写 description > AI 自动摘要 > Markdown 正文前 150 字

建议为重要文章手写描述，以获得更好的 SEO 效果
如果省略描述，系统会自动使用 AI 生成的摘要（需运行 pnpm generate:summaries）
如果既没有手写描述也没有 AI 摘要，则自动提取文章正文的前 150 个字符

关于 link 字段（自定义 URL）：

⚠️ 重要：link 字段会被自动转换为小写，以保持 URL 的一致性和规范性。

规范化行为：无论你输入 MyPost、myPost 还是 mypost，最终 URL 都会是 /post/mypost
文件名大小写无关：文章文件名可以使用任意大小写（如 MyPost.md），系统会自动处理
AI 摘要和相似度：生成的 summaries.json 和 similarities.json 中的 key 也会统一为小写
最佳实践：建议直接使用小写和连字符（如 my-awesome-post），避免混淆

# ✅ 推荐写法
link: my-awesome-post  # URL: /post/my-awesome-post

# ⚠️ 会被转为小写
link: MyAwesomePost    # URL: /post/myawesomepost（不是 /post/MyAwesomePost）
link: My-Awesome-Post  # URL: /post/my-awesome-post

如果省略 link 字段，系统会使用文件名（同样会转为小写）：

# 文件: src/content/blog/MyPost.md
# 省略 link 字段 → URL: /post/mypost

分类系统

astro-koharu 支持灵活的分类配置：

单层分类：

categories:
  - 工具 # 或者 ['工具']

对应 URL: /categories/tools（根据 categoryMap 映射）

多层嵌套分类：

categories:
  - [笔记, 前端, React]

这会创建层级关系：笔记 → 前端 → React

对应 URL: /categories/note/front-end/react

标签系统

标签是扁平的，不支持层级：

tags:
  - JavaScript
  - TypeScript
  - 学习笔记

所有标签会在 /tags 页面展示，点击标签可查看该标签下的所有文章。

草稿功能

设置 draft: true 将文章标记为草稿：

---
title: 未完成的文章
draft: true
---

行为：

本地开发 (pnpm dev)：草稿可见，文章卡片右上角显示 "DRAFT" 标识
生产构建 (pnpm build)：草稿自动过滤，不会出现在任何列表中

置顶功能

设置 sticky: true 将文章置顶：

---
title: 重要公告
sticky: true
---

行为：

置顶文章显示在首页 "置顶文章" 区域
置顶文章按日期排序（最新的在前）
不影响其他页面（分类、标签、归档）的排序

系列文章

配置了 featuredSeries 的系列（见基本配置），其分类下的文章会：

拥有专属的系列页面（URL 由 slug 决定，如 /weekly、/reading）
不出现在普通文章列表（/posts）中
如果系列设置了 highlightOnHome: true，最新一篇会在首页高亮显示

示例：

---
title: FE Bits Vol.16
categories:
  - 周刊 # 对应某个 featuredSeries 的 categoryName
excludeFromSummary: true # 可选：排除 AI 摘要生成
---

---
title: 《代码大全》读书笔记
categories:
  - 书摘 # 对应另一个 featuredSeries 的 categoryName
---

提示：文章的 categories 字段需要与 featuredSeries 中某个系列的 categoryName 匹配才会被归入该系列。

独立页面

除了博客文章外，你可以在 src/pages/ 目录下创建 .md 文件来添加独立页面（如"关于"、"歌单"等）。这些页面使用 PageLayout.astro 布局，支持完整的 Markdown 增强语法。

创建独立页面：

在 src/pages/ 目录下新建 .md 文件：

---
layout: ../layouts/PageLayout.astro
title: "歌单"
description: "我喜欢的音乐"
coverTitle: "我的歌单"
comments: false
---

页面内容...

Frontmatter 字段：

字段	必填	说明
`layout`	✅	固定为 `../layouts/PageLayout.astro`
`title`	✅	页面标题（用于浏览器标签页）
`description`	❌	页面描述（用于 SEO）
`coverTitle`	❌	封面显示的标题（默认使用 `title`）
`comments`	❌	是否显示评论区（默认 `true`）

添加导航入口：

在 config/site.yaml 的 navigation 中添加对应菜单项：

navigation:
  # ...
  - name: 歌单
    path: /music
    icon: ri:music-2-fill

提示：src/pages/ 下所有 .md 文件会被 Koharu CLI 的备份功能自动覆盖，无需额外配置。

界面功能

主题切换

点击右上角的太阳/月亮图标切换深色/浅色模式。

代码高亮：

浅色模式：github-light
深色模式：github-dark

全站搜索

基于 Pagefind 的静态站点搜索，无需后端服务器。

打开搜索：

点击导航栏搜索图标
快捷键：Cmd/Ctrl + K

特性：

支持中文分词
实时搜索结果
高亮匹配关键词
显示文章摘要和元信息

文章阅读功能

目录导航 (Table of Contents)：

自动提取文章标题（h2-h6）生成目录
使用 CSS 计数器自动为标题添加层级编号（如 1., 1.1., 1.1.1.）
支持通过 frontmatter 的 tocNumbering: false 字段关闭编号显示
点击目录项跳转到对应章节
滚动时自动高亮当前章节
桌面端显示在右侧边栏，移动端折叠

目录编号控制：

---
title: 我的文章
tocNumbering: false # 关闭目录编号（默认为 true）
---

默认情况下，所有文章的目录都会显示层级编号
设置 tocNumbering: false 可以关闭特定文章的编号显示
编号通过 CSS 计数器实现，零运行时开销
同时适用于桌面端侧边栏和移动端下拉目录

阅读进度条：

页面顶部显示阅读进度
实时更新当前阅读位置

标题锚点链接：

每个标题自动生成 ID
悬停标题时显示 # 链接图标
点击可复制带锚点的 URL

系列文章导航：

基于最深层分类自动分组
按发布日期排序
显示文章标题和封面

阅读时间估算：

文章卡片显示预计阅读时间（基于字数计算）。

移动端文章阅读头部：

在移动端（≤992px）浏览文章时，顶部导航栏会显示专为阅读优化的头部：

圆形阅读进度 - 实时显示当前阅读进度的圆形进度条
当前章节标题 - 显示当前所在的 H2/H3 章节标题，切换时带有平滑动画
可展开目录 - 点击标题区域可展开完整的文章目录，快速跳转到任意章节

特性：

滚动时自动更新当前章节
支持 prefers-reduced-motion 减少动画

响应式设计

桌面端：

双栏布局（主内容 + 侧边栏）
固定导航栏
悬浮目录

平板：

自适应布局调整
简化侧边栏

移动端：

单栏布局
抽屉式导航菜单（汉堡菜单）
折叠式目录
触摸优化的交互
文章页专属阅读头部（进度圈 + 当前标题 + 可展开目录）

特色功能

系列文章系统

featuredSeries 支持配置多个系列，每个系列会自动生成独立页面：

专属系列页面 (/{slug})：

每个启用的系列都有独立页面（如 /weekly、/reading）
显示该系列的所有文章
系列头图和介绍
相关链接（GitHub, RSS 等）

首页展示：

设置 highlightOnHome: true 的系列，其最新文章会在首页高亮显示
设置 highlightOnHome: false 的系列不在首页展示
所有系列文章独立于普通文章列表

设计说明：分离关注点

featuredSeries 的设计初衷是将高产出分类从首页分离，避免首页被单一类型文章刷屏。适用场景：

周刊/日记：更新频繁，数量庞大

读书笔记/书摘：独立成系列，方便按系列浏览

任何文章数量较多的分类：当某分类文章数量远超其他分类时

首页行为：

系列文章从首页主列表排除

设置 highlightOnHome: true 时，最新一篇在首页顶部高亮

其余文章通过系列专属页面（如 /weekly）访问

其他页面正常展示：系列文章在归档、分类、标签、搜索等页面仍与普通文章一起显示，仅首页主列表做了分离。

配置示例：

featuredSeries:
  - slug: weekly
    categoryName: 周刊
    highlightOnHome: true # 首页展示最新周刊
    # ...
  - slug: reading
    categoryName: 书摘
    highlightOnHome: false # 不在首页展示
    # ...

归档页面

访问 /archives 查看所有文章的归档视图：

按年份分组
显示每年的文章数量
时间线式展示
包含文章发布日期、标题、分类

友链系统

访问 /friends 查看友情链接页面：

功能：

友链卡片展示
友链申请表单（可自定义）
支持头像、名称、描述、链接

LQIP（低质量图片占位符）

LQIP（Low Quality Image Placeholder）是一种图片加载优化技术，在高清图片加载完成前，先显示一个低质量的占位符，避免页面出现空白或布局抖动。

特性：

构建时自动提取图片主色调，生成 CSS 渐变占位符
⚡ 零运行时开销 —— 纯 CSS 实现，无需 JavaScript 解码
极小数据体积 —— 每张图片仅需 18 字符存储
外部图片自动降级为纯色占位符

支持的组件：

文章卡片封面 (PostItemCard)
页面横幅 (Cover)
分类卡片背景 (CategoryCards)
系列封面 (SeriesCover)
侧边栏头像 (HomeInfo)

使用方式：

# 生成 LQIP 数据（处理 public/img/ 下所有图片）
pnpm generate:lqips

生成效果：

LQIP 数据保存在 src/assets/lqips.json，格式如下：

{
  "cover/1.webp": "87a3c4c2dfefbddae9",
  "cover/2.webp": "6e3b38ae7472af7574"
}

每个值是 18 个十六进制字符（3 个颜色），运行时解码为 CSS 渐变：

linear-gradient(135deg, #87a3c4 0%, #c2dfef 50%, #bddae9 100%)

原理：

使用 sharp 将图片缩放到 2×2 像素
提取四象限的平均色（左上、右上、左下、右下）
选取 3 个颜色生成 135 度斜向渐变
存储为紧凑的十六进制字符串

在组件中使用：

---
import { getLqipStyle, getLqipProps } from '@lib/lqip';

// 方式 1：直接获取样式字符串
const style = getLqipStyle('/img/cover/1.webp');
// 返回: "background-image:linear-gradient(...)"

// 方式 2：获取完整的 props（支持外部图片降级）
const lqipProps = getLqipProps(coverUrl);
// 本地图片返回: { style: "background-image:..." }
// 外部图片返回: { class: "lqip-fallback" }
---

<div style={style}>
  <img src="/img/cover/1.webp" />
</div>

注意事项：

生成的 src/assets/lqips.json 需要提交到 git
添加新图片后需要重新运行 pnpm generate:lqips
外部图片（http/https 开头）会自动使用纯色占位符降级

模型	大小	维度	优势
`Snowflake/snowflake-arctic-embed-m-v2.0`	~90MB	768	质量高，中英文均衡
`sentence-transformers/all-MiniLM-L6-v2`	~23MB	384	轻量快速
`BAAI/bge-small-zh-v1.5`	~95MB	512	中文专用

AI 自动摘要

基于 transformers.js 的智能摘要生成系统，使用先进的 AI 模型为文章自动生成高质量摘要。

与相关文章推荐的关系：

AI 摘要功能与相关文章推荐功能相辅相成：

相似度计算需要读取文章全文，计算成本较高（约 3-5 分钟）
AI 摘要可以在不读取全文的情况下提供优质描述，同时生成的摘要也能帮助改善相似度计算的效果
两者共享相同的模型缓存机制，节省存储空间

特性：

基于先进的文本生成模型（Xenova/LaMini-Flan-T5-783M）
自动为缺少描述的文章生成摘要
✨ 文章详情页支持打字机动画展示，增强阅读体验
智能 fallback：优先使用手写 description，无描述时自动使用 AI 摘要
构建时预生成，运行时零开销
♿ 支持无障碍访问和 prefers-reduced-motion

使用方式：

# 生成 AI 摘要（本地运行，首次会下载模型，约需 5-10 分钟）
pnpm generate:summaries

# 生成的文件要提交到 git，然后可以在 Vercel 等平台直接使用

生成效果：

AI 摘要会保存在 src/assets/summaries.json 文件中，格式如下：

{
  "article-slug": {
    "title": "文章标题",
    "summary": "AI 生成的摘要内容..."
  }
}

在哪里使用：

文章详情页：面包屑导航下方显示可折叠的 AI 摘要卡片
- 默认收起状态，点击"展开"按钮触发
- 展开后以打字机动画逐字显示摘要内容
- 打字机动画仅播放一次，支持 prefers-reduced-motion 用户偏好
文章卡片：作为描述的 fallback
- 优先级：手写 description > AI 摘要 > Markdown 前 150 字
- 在文章列表、首页、分类页等处自动使用

模型选择：

默认使用 Xenova/LaMini-Flan-T5-783M 模型：

模型大小：约 300MB（首次运行会自动下载到 .cache/transformers 目录）
生成质量：高质量的中英文摘要生成
生成时间：约 5-10 分钟（169 篇文章）

如需更换模型，编辑 src/scripts/generateSummaries.ts 中的 MODEL_NAME：

const MODEL_NAME = "Xenova/LaMini-Flan-T5-783M";
// 可选替代方案：
// const MODEL_NAME = 'Xenova/distilbart-cnn-6-6'; // 更快，英文效果好
// const MODEL_NAME = 'facebook/bart-large-cnn';   // 质量更高，但速度较慢

配置提示词：

可以自定义生成摘要的提示词，编辑 src/scripts/generateSummaries.ts 中的 PROMPT_TEMPLATE：

const PROMPT_TEMPLATE = (title: string, content: string) =>
  `请为以下文章生成一段简洁的摘要（100-150字）：\n\n标题：${title}\n\n内容：${content}`;

注意事项：

需要本地运行生成脚本（Vercel 等平台无法运行大模型）
生成的 src/assets/summaries.json 需要提交到 git
如果没有生成摘要文件，会自动 fallback 到 Markdown 文本提取
模型文件会缓存在 .cache/transformers 目录（已添加到 .gitignore）
首次运行需要下载模型，建议在网络良好的环境下进行

最佳实践：

与相似度计算配合使用：

# 先生成摘要
pnpm generate:summaries
# 再计算相似度（可以使用摘要代替全文，提升速度）
pnpm generate:similarities

选择性生成摘要：为了节省时间，脚本会跳过已有 description 的文章
提交到版本控制：将生成的 JSON 文件提交到 git，避免在 CI/CD 环境重复生成

圣诞特辑

节日限定的圣诞氛围特效系统，包含多种可独立开关的视觉效果，为博客增添节日气氛。

特性：

雪花飘落 —— Canvas 实现的雪花动画，分前景和背景两层，支持视差效果
圣诞配色 —— 红绿金主题色替换默认粉蓝配色，支持深色/浅色模式
圣诞帽装饰 —— 侧边栏头像上的圣诞帽
圣诞灯串 —— Header 顶部的装饰灯串动画
圣诞饰品切换 —— 导航栏的装饰饰品
运行时开关 —— 右下角浮动按钮可随时切换特效，设置自动保存

配置方式：

编辑 config/site.yaml 中的 christmas 配置：

christmas:
  enabled: true # 总开关
  features:
    snowfall: true # 雪花飘落
    christmasColorScheme: true # 圣诞配色
    christmasCoverDecoration: true # 灯串装饰
    christmasHat: true # 圣诞帽
    readingTimeSnow: true # 阅读时间雪花特效
  snowfall:
    speed: 0.5 # 飘落速度（默认 0.5）
    intensity: 0.7 # 桌面端雪花密度（0-1）
    mobileIntensity: 0.4 # 移动端雪花密度（0-1）
    maxLayers: 6 # 最大雪花层数
    maxIterations: 8 # 最大迭代次数
    mobileMaxLayers: 4 # 移动端最大层数
    mobileMaxIterations: 6 # 移动端最大迭代次数

用户控制：

页面右下角悬浮按钮（雪花图标）可切换圣诞特效开关
用户偏好自动保存到 localStorage，跨会话保持
支持 prefers-reduced-motion 偏好，自动禁用动画

技术实现：

雪花使用 Canvas 2D 渲染，分层实现视差效果
配色通过 CSS 变量覆盖，零运行时开销
状态管理使用 nanostores，支持跨组件同步
完全响应式，移动端自动降低雪花密度

关闭圣诞特效：

设置 christmasConfig.enabled = false 即可完全关闭所有圣诞特效。

站点公告系统

无后端的站点公告系统，支持在配置文件中管理公告，首次访问自动弹出，关闭后可通过页脚入口再次查看。

特性：

无后端 —— 公告内容写在配置文件，无需数据库
Toast 通知 —— 右下角浮动通知，支持多条堆叠显示
多条公告 —— 支持配置多条公告，按优先级排序
时间控制 —— 支持设置公告的开始/结束日期，自动控制显示
自定义颜色 —— 每条公告可设置独立颜色，覆盖默认类型颜色
时间线弹窗 —— 公告列表采用时间线样式，带渐变连接线
Hover 已读 —— 悬停 Toast 1 秒后自动标记已读
已读追踪 —— localStorage 记录已读状态，返回访问不重复弹出
再次查看 —— 页脚入口可随时查看所有公告，带未读红点提示

配置方式：

编辑 config/site.yaml 添加公告：

announcements:
  - id: welcome-2026 # 唯一标识
    title: 2026 年新年快乐! # 公告标题
    content: 新年快乐! 感谢大家一直以来的支持~ # 公告内容
    type: info # 类型：info | warning | success | important
    priority: 300 # 优先级（越高越先显示）
    color: "#ED788C" # 自定义颜色（可选，覆盖 type 默认色）
    publishDate: "2026-01-01" # 显示日期（可选，用于时间线展示）
    startDate: "2025-12-31T00:00:00+08:00" # 开始日期（可选）
    endDate: "2026-01-15T23:59:59+08:00" # 结束日期（可选）
  - id: site-update-01
    title: 站点更新公告
    content: 新增站点公告系统，现在支持多条公告同时显示！
    type: info
    priority: 500
    color: "#6366F1"
    publishDate: "2025-01-02"

如果需要添加链接（可选）：

announcements:
  - id: example-with-link
    title: 示例公告
    content: 公告内容
    type: info
    link:
      url: https://example.com
      text: 了解更多
      external: true

公告类型样式：

类型	说明	默认颜色
`info`	信息通知	蓝色 (#3b82f6)
`warning`	警告提示	黄色 (#eab308)
`success`	成功消息	绿色 (#22c55e)
`important`	重要公告	红色 (#ef4444)

设置 color 字段可覆盖上述默认颜色

交互流程：

首次访问：0.5 秒后自动弹出未读公告 Toast（多条堆叠显示）
Hover 已读：悬停在 Toast 上 1 秒后自动标记已读
手动关闭：点击 Dismiss 关闭 Toast
点击"View all"：关闭所有 Toast，打开时间线弹窗
时间线弹窗：点击公告卡片标记已读，显示发布日期和渐变连接线
页脚入口：随时可点击查看所有公告，未读时显示红点
返回访问：只显示真正未读的公告

注意事项：

公告 id 必须唯一，用于追踪已读状态
省略 startDate 表示立即生效，省略 endDate 表示永不过期
publishDate 用于时间线弹窗中的日期显示，省略时使用 startDate
过期公告建议从配置中删除，保持配置简洁
已读状态存储在 localStorage，key 为 announcement-read-ids

Markdown 增强

语法支持：

GitHub Flavored Markdown (GFM)
- 表格
- 任务列表
- 删除线
- 自动链接

Mermaid 图表：

支持在 Markdown 中使用 Mermaid 语法绘制流程图、时序图、架构图等。

```mermaid
flowchart LR
    A[构建时脚本] --> B[JSON 数据文件] --> C[运行时工具函数]
```

flowchart LR
    A[构建时脚本] --> B[JSON 数据文件] --> C[运行时工具函数]

支持的图表类型：

flowchart / graph - 流程图
sequenceDiagram - 时序图
classDiagram - 类图
stateDiagram - 状态图
erDiagram - ER 图
gantt - 甘特图
pie - 饼图
mindmap - 思维导图

图表会自动跟随深色/浅色主题切换。更多语法参考 Mermaid 官方文档。

Infographic 信息图：

支持使用 @antv/infographic 在 Markdown 中绘制精美的信息图表，适合展示流程、对比、层级、统计等数据。

使用方式：在代码块中使用 infographic 标记，第一行指定模板名称，然后使用类似 YAML 的语法定义数据：

```infographic
infographic list-grid-badge-card
data
  title 技术栈
  desc 我的常用技术栈
  items
    - label TypeScript
      desc 类型安全的 JavaScript
      icon mdi/language-typescript
    - label React
      desc 用户界面库
      icon mdi/react
    - label Astro
      desc 现代化静态站点生成器
      icon mdi/rocket-launch
```

infographic list-grid-badge-card
data
  title 技术栈
  desc 我的常用技术栈
  items
    - label TypeScript
      desc 类型安全的 JavaScript
      icon mdi/language-typescript
    - label React
      desc 用户界面库
      icon mdi/react
    - label Astro
      desc 现代化静态站点生成器
      icon mdi/rocket-launch

可用模板类型：

列表类 (list-*)：展示信息列表
- list-grid-badge-card - 卡片网格布局
- list-grid-candy-card-lite - 糖果风格卡片
- list-row-horizontal-icon-arrow - 水平图标箭头列表
流程/顺序类 (sequence-*)：展示步骤、流程或阶段
- sequence-zigzag-steps-underline-text - 之字形步骤
- sequence-circular-simple - 圆形流程
- sequence-roadmap-vertical-simple - 垂直路线图
- sequence-pyramid-simple - 金字塔结构
对比类 (compare-*)：二元或多元对比
- compare-binary-horizontal-simple-fold - 水平二元对比
- compare-swot - SWOT 分析
- compare-hierarchy-left-right-circle-node-pill-badge - 层级左右对比
层级类 (hierarchy-*)：展示树形结构
- hierarchy-tree-tech-style-capsule-item - 科技风格树形图
- hierarchy-tree-curved-line-rounded-rect-node - 曲线连接树形图
图表类 (chart-*)：数据可视化
- chart-column-simple - 柱状图
- chart-bar-plain-text - 条形图
- chart-pie-plain-text - 饼图
- chart-line-plain-text - 折线图
其他
- quadrant-* - 象限分析图
- relation-* - 关系图

数据字段说明：

title - 标题（可选）
desc - 描述文本（可选）
items - 条目数组，每个条目可包含：
- label - 主标签文本
- value - 数值（用于图表类模板）
- desc - 描述文本
- icon - 图标名称（格式：mdi/icon-name）
- children - 子条目（用于层级结构）

主题定制：

可以在数据后添加 theme 块自定义颜色：

```infographic
infographic sequence-pyramid-simple
data
  items
    - label 基础层
    - label 中间层
    - label 顶层
theme
  palette
    - #3b82f6
    - #8b5cf6
    - #f97316
```

信息图会自动跟随深色/浅色主题切换，并使用项目的寒蝉全圆体字体渲染。更多模板和语法参考 Infographic 官方文档。

代码高亮：

基于 Shiki
支持双主题（深色/浅色）
支持语言标注
行号显示

示例：

```javascript
function hello() {
  console.log("Hello, world!");
}
```

function hello() {
  console.log("Hello, world!");
}

标题自动链接：

所有标题自动生成可点击的锚点链接。

链接自动嵌入：

独行的特殊链接会自动转换为嵌入组件：

Twitter/X 链接：自动嵌入 Tweet 组件
CodePen 链接：自动嵌入交互式 CodePen 演示
其他链接：显示 OG 预览卡片（包含标题、描述、图片等）

示例：

<!-- 独行链接会被嵌入 -->

https://x.com/vercel_dev/status/1997059920936775706

https://codepen.io/botteu/pen/YPKBrJX/

https://github.com/vercel/react-tweet

反爬严格，获取不到元信息的链接

https://zhuanlan.zhihu.com/p/1900483903984243480

<!-- 段落中的链接保持不变 -->

这是一个 [普通链接](https://example.com)，不会被嵌入。

See the Pen YPKBrJX by botteu (@botteu) on CodePen.

github.com

GitHub - vercel/react-tweet: Embed tweets in your React application.

Embed tweets in your React application. Contribute to vercel/react-tweet development by creating an account on GitHub.

https://github.com/vercel/react-tweet

反爬严格，获取不到元信息的链接

https://zhuanlan.zhihu.com/p/1900483903984243480

zhuanlan.zhihu.com

这是一个普通链接，不会被嵌入。

Shoka 兼容 Markdown 语法：

astro-koharu 从 Hexo Shoka 主题迁移了一套丰富的 Markdown 扩展语法，所有功能均可通过 config/site.yaml 的 content 配置项独立开关。

文字特效（enableShokaEffects）：

支持多种行内文字装饰效果：

语法	效果	说明
`++文字++`	下划线	`<ins>` 标签
`++文字++{.wavy}`	波浪下划线	支持 `.wavy` 修饰符
`++文字++{.dot}`	着重点	支持 `.dot` 修饰符
`++文字++{.primary}`	彩色下划线	支持 `.primary` `.success` `.warning` `.danger` `.info`
`==文字==`	高亮	`<mark>` 标签
`~文字~`	下标	`<sub>` 标签，如 H₂O
`^文字^`	上标	`<sup>` 标签，如 E=mc²

示例效果：

这是下划线文字波浪下划线着重点标记

主色调成功警告危险信息

这是高亮文字

H₂O 是水的化学式，E = mc² 是质能方程

颜色文字与特殊样式（enableShokaAttrs）：

使用 文字 语法为文字添加颜色和样式：

[红色]{.red} [粉色]{.pink} [橙色]{.orange} [黄色]{.yellow}
[绿色]{.green} [水色]{.aqua} [蓝色]{.blue} [紫色]{.purple} [灰色]{.grey}

[这段文字会有彩虹渐变效果]{.rainbow}

[Ctrl]{.kbd} + [C]{.kbd} 复制，[Ctrl]{.kbd} + [V]{.kbd} 粘贴

[默认]{.label .default} [主要]{.label .primary} [信息]{.label .info}
[成功]{.label .success} [警告]{.label .warning} [危险]{.label .danger}

示例效果：

红色粉色橙色黄色绿色水色蓝色紫色灰色

这段文字会有彩虹渐变效果

Ctrl + C 复制，Ctrl + V 粘贴

默认主要信息成功警告危险

隐藏文字 / Spoiler（enableShokaSpoiler）：

这里有一段!!隐藏文字，点击显示!!

这里有一段!!模糊文字，鼠标悬停显示!!{.blur}

示例效果：

这里有一段隐藏文字，点击显示

这里有一段模糊文字，鼠标悬停显示

默认模式：点击后粒子消散动画揭示文字（基于 spoilerjs Web Component）
.blur 模式：鼠标悬停时模糊消失

注音标注 / Ruby（enableShokaRuby）：

为 CJK 文字添加注音，适用于日语假名、汉语拼音等：

{漢字^かんじ}的注音示例

{取り返す^とりかえす}是日语中"取回"的意思

示例效果：

{漢字^{かんじ}的注音示例。{取り返す}とりかえす}是日语中"取回"的意思。

渲染为 HTML <ruby> 标签，浏览器原生支持。

提醒块 / Note Blocks（enableShokaContainers）：

使用 ::: 语法创建不同样式的提醒块：

:::default
这是默认提醒块
:::

:::primary
这是主要提醒块，用于重要提示
:::

:::info
这是信息提醒块
:::

:::success
这是成功提醒块
:::

:::warning
这是警告提醒块
:::

:::danger
这是危险提醒块
:::

:::info no-icon
这是没有图标的信息块
:::

示例效果：

这是信息提醒块，用于提供额外信息

这是警告提醒块，请注意

这是危险提醒块，务必谨慎

支持的样式：default、primary、info、success、warning、danger。添加 no-icon 可隐藏图标。提醒块内部支持嵌套 Markdown 语法。

折叠块 / Collapse（enableShokaContainers）：

使用 +++ 语法创建可折叠内容（渲染为 <details> + <summary>）：

+++primary 点击展开详细内容
折叠的内容，支持 **Markdown** 格式化。

- 列表项 1
- 列表项 2
+++

+++warning 注意事项
需要注意的内容
+++

+++danger 危险操作
请确保你知道自己在做什么！
+++

示例效果：

点击展开详细内容

折叠的内容，支持 Markdown 格式化。

列表项 1
列表项 2

注意事项

需要注意的内容

支持的样式：primary、info、success、warning、danger。

标签卡 / Tabs（enableShokaContainers）：

使用 ;;; 语法创建标签页切换，同一组 ID 的标签卡会自动组合：

;;;mygroup JavaScript
```js
console.log('Hello, World!');
```
;;;

;;;mygroup Python
```python
print('Hello, World!')
```
;;;

;;;mygroup Rust
```rust
fn main() {
    println!("Hello, World!");
}
```
;;;

示例效果：

JavaScript Python Rust

console.log('Hello, World!');

print('Hello, World!')

fn main() {
    println!("Hello, World!");
}

;;;groupId 标签名 定义一个标签页，同一 groupId 的标签自动组合
第一个标签默认激活
标签内支持任意 Markdown 内容

友链卡片（enableShokaHexoTags）：

使用 {% links %} 标签在文章中插入友链卡片网格：

{% links %}
- site: 博客名称
  url: https://example.com
  owner: 站长昵称
  desc: 站点描述
  image: https://example.com/avatar.png
  color: '#ed788b'
- site: 另一个博客
  url: https://example2.com
  owner: Alice
  desc: 一个热爱技术的博客
  image: https://api.dicebear.com/7.x/avataaars/svg?seed=Alice
  color: '#BEDCFF'
{% endlinks %}

示例效果：

卡片数据使用 YAML 格式，支持 site、url、owner、desc、image、color 字段。

音频播放器（enableShokaHexoTags）：

使用 {% media audio %} 标签嵌入音频播放器，支持网易云音乐等平台（通过 Meting API 解析）：

{% media audio %}
- name: 歌曲名称
  url: https://music.163.com/#/song?id=3339210292
{% endmedia %}

示例效果：

支持歌单模式，可配置多个分组：

{% media audio %}
- title: 歌单名称 1
  list:
    - https://music.163.com/#/playlist?id=8676645748
- title: 歌单名称 2
  list:
    - https://music.163.com/#/playlist?id=17606384886
{% endmedia %}

视频播放器（enableShokaHexoTags）：

使用 {% media video %} 标签嵌入视频播放器：

{% media video %}
- name: 视频 1
  url: https://example.com/video1.mp4
- name: 视频 2
  url: https://example.com/video2.mp4
{% endmedia %}

多个视频时自动显示播放列表。

练习题系统（enableQuiz）：

支持四种交互式题型，适合教程和学习笔记。需在文章 frontmatter 中设置 quiz: true。

单选题：

- 下列哪个是 JavaScript 的基本数据类型？{.quiz}
  - Object{.options}
  - Array{.options}
  - Symbol{.correct}
  - Function{.options}

> 解析：Symbol 是 ES6 引入的基本数据类型。

示例效果：

下列哪个是 JavaScript 的基本数据类型？
- Object
- Array
- Symbol
- Function

解析：Symbol 是 ES6 引入的基本数据类型，而 Object、Array、Function 都是引用类型。

选项标记为正确答案，{.options} 为干扰项

多选题：

- 以下哪些是 CSS 布局方式？{.quiz .multi}
  - Flexbox{.correct}
  - jQuery{.options}
  - Grid{.correct}
  - Float{.correct}

> 解析：Flexbox、Grid 和 Float 都是 CSS 布局方式。

示例效果：

以下哪些是 CSS 布局方式？
- Flexbox
- jQuery
- Grid
- Float

解析：Flexbox、Grid 和 Float 都是 CSS 布局方式。jQuery 是一个 JavaScript 库。

添加 .multi 标记启用多选模式

判断题：

- `const` 声明的变量不能重新赋值，但可以修改其属性。{.quiz .true}

> 解析：`const` 只保证变量绑定不可变。

- HTML 是一种编程语言。{.quiz}

> 解析：HTML 是标记语言，不是编程语言。

示例效果：

const 声明的变量不能重新赋值，但可以修改其属性。

解析：const 只保证变量绑定不可变，如果变量指向一个对象，其属性仍然可以修改。

HTML 是一种编程语言。

解析：HTML（超文本标记语言）是一种标记语言，不是编程语言。

添加 .true 表示陈述正确，不添加 .true 则表示错误

填空题：

- CSS 中，[Flexbox]{.gap} 适合一维布局，[Grid]{.gap} 适合二维布局。{.quiz .fill}

> 常见错误：[Float]{.mistake}

示例效果：

CSS 中，Flexbox 适合一维布局，Grid 适合二维布局。

常见错误：Float

[答案] 标记正确答案（支持多个空）
[错误答案] 标记常见错误（首次答错时提示）
> 引用块内容为解析说明

数学公式（enableMath）：

基于 KaTeX 渲染数学公式。需在文章 frontmatter 中设置 math: true：

行内公式：$E = mc^2$

块级公式：

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

示例效果：

行内公式：E=mc2E = mc^2E=mc2

块级公式：

∑n=1∞1n2=π26\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}n=1∑∞n21=6π2

代码块增强（enableCodeMeta）：

代码块支持额外的元数据标注：

```js title="hello.js" url="https://example.com" linkText="查看源码" mark:1,3
const greeting = 'Hello';
const name = 'World';
console.log(`${greeting}, ${name}!`);
```

```bash command:("$":1-3)
npm install astro
npm run dev
npm run build
```

元数据	说明
`title="文件名"`	显示代码块标题
`url="链接"`	添加外部源码链接
`linkText="文字"`	自定义链接文字（默认为 URL）
`mark:1,3`	高亮指定行
`command:("$":1-3)`	标记 shell 命令行（显示 `$` 前缀）

示例效果：

const greeting = 'Hello';
const name = 'World';
console.log(`${greeting}, ${name}!`);

npm install astro
npm run dev
npm run build

Shoka 功能配置总览：

所有 Shoka 兼容功能均可在 config/site.yaml 的 content 部分独立开关：

content:
  # Shoka 兼容功能（默认全部启用，设为 false 可关闭）
  enableShokaContainers: true   # :::提醒块 ;;;标签卡 +++折叠块
  enableShokaAttrs: true        # text 属性语法
  enableShokaEffects: true      # ++下划线++ ==高亮== ~下标~ ^上标^
  enableShokaSpoiler: true      # !!隐藏文字!!
  enableShokaRuby: true         # {文字^注音} 注音标注
  enableShokaHexoTags: true     # {% links %} {% media %} Hexo 标签
  enableMath: true              # $数学公式$ KaTeX 渲染
  enableCodeMeta: true          # 代码块增强 (title, mark, command)
  enableQuiz: true              # 练习题交互功能
  enableEncryptedBlock: true    # :::encrypted{password="..."} 加密内容块

提示：完整的语法演示可参考 Shoka 主题 Markdown 语法演示文章。

内容加密（enableEncryptedBlock）：

博客支持两种加密方式，满足不同的内容保护需求：

1. 加密块 —— 文章局部加密

在文章中使用 :::encrypted{password="..."} 语法包裹需要加密的内容：

这部分内容公开可见。

:::encrypted{password="demo"}
这段内容需要输入密码 "demo" 才能查看。

支持完整的 Markdown 语法，包括代码块、列表、图片等。
:::

这部分也是公开的。

加密块适合在一篇文章中部分隐藏敏感内容（如答案、剧透、私密笔记），其余内容正常展示。需要在 config/site.yaml 中启用 enableEncryptedBlock: true。

2. 加密文章 —— 整篇文章加密

在文章的 frontmatter 中添加 password 字段即可加密整篇文章：

---
title: 我的私密文章
date: 2026-01-01
password: mySecretPassword
categories:
  - 笔记
---

这里的所有内容都会被加密...

加密文章会显示一个全屏的解锁界面，输入正确密码后才能查看内容。解锁后代码高亮、目录导航、Mermaid 图表等增强功能会自动重新初始化。

安全模型说明：

加密功能使用 AES-256-GCM 算法，安全模型如下：

构建时加密：密码仅在 pnpm build 时用于加密，生成的 HTML 中不包含密码明文
客户端解密：读者在浏览器中输入密码后，通过 Web Crypto API 在本地解密，密码不会发送到任何服务器
密钥派生：使用 PBKDF2（100,000 次迭代）从密码派生加密密钥，提高暴力破解成本
搜索排除：加密内容自动添加 data-pagefind-ignore，不会被 Pagefind 搜索索引

⚠️ 注意：此加密设计的主要目的是防止搜索引擎和爬虫索引加密内容，而非抵御针对性攻击。密文和盐值嵌入在公开的 HTML 中，理论上可被离线暴力破解。请使用强密码，不要用于保护高度敏感的信息。

加密文章的特殊行为：

方面	行为
RSS 订阅	标题前加前缀，内容替换为"此文章已加密"提示
SEO / meta	description 使用 frontmatter 中的 `description`（若未设置则显示通用加密提示）
搜索索引	加密内容不会被 Pagefind 索引
目录导航	解锁前不显示，解锁后自动重建
AI 摘要	基于加密前的原文生成（构建时可访问明文）

其他增强：

自动目录生成
阅读时间计算
外部链接自动添加 target="_blank"

多语言支持（i18n）

博客内置完整的国际化支持，可轻松添加多种语言。

基本配置

在 config/site.yaml 的 i18n 部分配置支持的语言：

i18n:
  defaultLocale: zh        # 默认语言（URL 无前缀）
  locales:
    - code: zh
      label: 中文
    - code: en
      label: English
      # enabled: false     # 设为 false 可暂时禁用（保留内容但不生成路由）

配置多语言后：

默认语言的页面 URL 不带前缀（如 /post/hello）
其他语言自动加前缀（如 /en/post/hello）
导航栏（桌面端）和移动端抽屉中自动显示语言切换器
每个语言各自生成独立的 RSS 订阅源（如 /en/rss.xml）
HTML <head> 中自动输出 hreflang 标签，有利于 SEO

如果只配置了一种语言，i18n 功能不会激活，不会产生额外的路由或 UI 元素。

翻译体系

i18n 系统采用两层翻译架构：

1. UI 字符串（TypeScript）

界面上的按钮文字、提示信息等 UI 文本通过 TypeScript 翻译字典管理，位于 src/i18n/translations/ 目录：

zh.ts：默认语言（中文），包含所有翻译 key（约 170 个），是唯一的 source-of-truth
en.ts：英文翻译，只需提供需要覆盖的 key，未提供的自动回退到中文

翻译字符串支持 {param} 占位符插值：

// zh.ts
'post.totalPosts': '共 {count} 篇文章',

// en.ts
'post.totalPosts': '{count} posts',

2. 内容字符串（YAML）

分类名、系列名、精选分类描述等内容级文本通过 config/i18n-content.yaml 管理。默认语言的值直接读取 config/site.yaml，此文件仅存放非默认语言的翻译：

en:
  categories:
    life: Life
    note: Notes
    tools: Tools
  series:
    weekly:
      label: My Weekly
      fullName: My Tech Weekly
  featuredCategories:
    life:
      label: Life
      description: Life journals and essays

其中 categories 的 key 是分类的 URL slug（对应 config/site.yaml 中 categoryMap 的值），series 的 key 是系列的 slug。

添加翻译文章

将翻译文章放在 src/content/blog/<locale>/ 目录下，保持与默认语言相同的路径结构：

src/content/blog/
├── life/hello-world.md            # 默认语言 (zh)
├── tools/getting-started.md       # 默认语言 (zh)
├── en/life/hello-world.md         # 英文翻译
└── en/tools/getting-started.md    # 英文翻译

回退机制：当用户切换到非默认语言时，系统会显示该语言已有的翻译文章，对于尚未翻译的文章则自动回退显示默认语言内容，并在文章顶部标注提示信息。

添加新语言

以添加日语（ja）为例：

在 config/site.yaml 的 i18n.locales 中添加新语言：

i18n:
  locales:
    - code: zh
      label: 中文
    - code: en
      label: English
    - code: ja
      label: 日本語

创建 UI 翻译文件 src/i18n/translations/ja.ts：

import type { UIStrings } from '../types';

export const uiStrings: UIStrings = {
  'nav.home': 'ホーム',
  'common.search': '検索',
  // ... 按需翻译，未提供的 key 自动回退到中文
};

在 src/i18n/translations/index.ts 中注册：

import { uiStrings as ja } from './ja';

export const translations: Record<string, DefaultUIStrings | UIStrings> = {
  zh,
  en,
  ja, // 新增
};

4.（可选）在 config/i18n-content.yaml 中添加日语的内容翻译。

5.（可选）在 src/content/blog/ja/ 目录下添加日语文章。

在组件中使用翻译

Astro 组件（.astro 文件）中：

---
import { getLocaleFromUrl, t, localizedPath } from '@/i18n';

const locale = getLocaleFromUrl(Astro.url.pathname);
---

<h1>{t(locale, 'post.totalPosts', { count: 10 })}</h1>
<a href={localizedPath('/archives', locale)}>归档</a>

React 组件（.tsx 文件）中：

import { useTranslation } from '@hooks/useTranslation';

function MyComponent() {
  const { t, locale } = useTranslation();
  return <button>{t('common.search')}</button>;
}

RSS 订阅

访问 /rss.xml 获取 RSS feed。启用多语言时，每个语言有独立的 RSS 源（如 /en/rss.xml）。

包含内容：

最新文章列表
文章摘要
发布日期
文章链接

数据统计

集成 Umami 分析（可选）。

在 config/site.yaml 中配置：

analytics:
  umami:
    enabled: true
    id: your-umami-id
    endpoint: https://stats.example.com

开发指南

目录结构

astro-koharu/
├── src/
│   ├── components/      # 组件
│   │   ├── common/      # 通用组件（错误边界等）
│   │   ├── ui/          # UI 组件（按钮、卡片等）
│   │   ├── layout/      # 布局组件（头部、侧边栏等）
│   │   ├── post/        # 文章相关组件
│   │   ├── category/    # 分类组件
│   │   └── theme/       # 主题切换
│   ├── content/
│   │   └── blog/        # 博客文章（Markdown）
│   │       └── en/      # 英文翻译文章（按 locale 子目录组织）
│   ├── i18n/            # 国际化模块
│   │   ├── config.ts    # locale 配置（读取 site.yaml）
│   │   ├── utils.ts     # 翻译函数、URL 工具
│   │   ├── content.ts   # 内容翻译加载（读取 i18n-content.yaml）
│   │   └── translations/  # UI 翻译字典（zh.ts, en.ts）
│   ├── layouts/         # 页面布局模板
│   ├── pages/           # 页面路由
│   │   └── [lang]/      # 非默认语言的镜像路由
│   ├── lib/             # 工具函数
│   ├── hooks/           # React hooks
│   ├── constants/       # 常量配置
│   ├── store/           # 全局状态（nanostores）
│   ├── scripts/         # 构建脚本
│   ├── styles/          # 全局样式
│   └── types/           # TypeScript 类型定义
├── public/              # 静态资源
│   └── img/             # 图片资源
├── config/
│   ├── site.yaml        # 站点配置（含分类映射、i18n 配置）
│   └── i18n-content.yaml  # 内容级翻译（分类名、系列名等）
├── astro.config.mjs     # Astro 配置
├── tailwind.config.mjs  # Tailwind 配置
└── tsconfig.json        # TypeScript 配置

路径别名

项目配置了以下路径别名（在 tsconfig.json 中）：

import { something } from "@/xxx"; // → src/xxx
import Component from "@components/xxx"; // → src/components/xxx
import { util } from "@lib/xxx"; // → src/lib/xxx
import config from "@constants/xxx"; // → src/constants/xxx
// ... 更多别名见 tsconfig.json

常用命令

# 开发
pnpm dev              # 启动开发服务器（默认 localhost:4321）

# 构建
pnpm build            # 构建生产版本
pnpm preview          # 预览生产构建

# 代码质量
pnpm lint             # 运行 ESLint
pnpm lint-md          # 检查 Markdown 文件
pnpm lint-md:fix      # 自动修复 Markdown 问题
pnpm knip             # 查找未使用的文件和依赖

# Koharu CLI
pnpm koharu                   # 交互式主菜单
pnpm koharu new               # 新建内容（交互式选择）
pnpm koharu new post          # 新建博客文章
pnpm koharu new friend        # 新建友情链接
pnpm koharu backup            # 备份博客内容（--full 完整备份）
pnpm koharu restore           # 还原备份（--latest, --dry-run）
pnpm koharu update            # 更新主题（--check, --clean, --rebase, --tag, --dry-run 等）
pnpm koharu generate          # 生成内容资产（交互式选择）
pnpm koharu generate lqips    # 生成 LQIP 占位符
pnpm koharu generate similarities  # 生成相似度向量
pnpm koharu generate summaries     # 生成 AI 摘要
pnpm koharu generate all      # 生成全部资产
pnpm koharu clean             # 清理旧备份（--keep N）
pnpm koharu list              # 查看所有备份

# 工具
pnpm change           # 生成 CHANGELOG.md（基于 git-cliff）

Docker 部署

astro-koharu 支持通过 Docker 进行容器化部署，适合需要自托管的场景。

快速开始：

# 1. 编辑 config/site.yaml，配置 comment.remark42 和 analytics.umami 部分

# 2. 构建并启动
docker compose -f docker/docker-compose.yml up -d --build

# 3. 访问
open http://localhost:4321

目录结构：

docker/
├── Dockerfile           # 多阶段构建配置
├── docker-compose.yml   # 编排配置
├── nginx/
│   └── default.conf     # Nginx 静态服务配置
└── rebuild.sh           # 便捷重建脚本

关于生成脚本：

以下脚本需要在本地运行，不能在 Docker 构建时执行：

脚本	原因
`pnpm generate:lqips`	使用 `sharp` 原生模块处理图片
`pnpm generate:similarities`	需下载 500MB+ 的 ML 模型
`pnpm generate:summaries`	需连接本地 LLM 服务器

推荐工作流：

# 本地开发：添加新图片或文章后
pnpm generate:all

# 提交生成的数据文件
git add src/assets/*.json
git commit -m "chore: update generated assets"

# 重建 Docker 容器
./docker/rebuild.sh

使用 rebuild.sh：

cd docker
./rebuild.sh

该脚本会：

检查环境变量文件
停止现有容器
重新构建并启动

评论与统计配置：

在 config/site.yaml 中配置评论系统和统计：

# 评论系统（可选）
comment:
  remark42:
    enabled: true
    host: https://your-remark-server.com/
    siteId: your-site-id

# 统计系统（可选）
analytics:
  umami:
    enabled: true
    id: your-umami-id
    endpoint: https://your-umami-server.com

Docker 端口可在 .env 中配置 BLOG_PORT=4321。

注意事项：

生成的 JSON 文件必须提交到 git，Docker 构建时会直接使用
如果忘记运行生成脚本，相关功能（LQIP 占位符、相关文章推荐等）将不可用
Docker 镜像基于 nginx
，仅包含静态文件，无需 Node.js 运行时

Koharu CLI

博客自带交互式命令行工具，提供备份还原、主题更新、内容生成、新建内容等功能。

启动方式：

pnpm koharu              # 交互式主菜单

新建内容

使用 CLI 快速创建博客文章和友链：

# 交互式选择创建类型（文章或友链）
pnpm koharu new

# 或直接指定类型
pnpm koharu new post     # 新建博客文章
pnpm koharu new friend   # 新建友情链接

新建博客文章功能：

交互式输入文章信息：
- 标题 - 文章标题（必填）
- Slug - 自定义 URL（可选，默认根据标题自动生成拼音）
- 描述 - 文章摘要（可选）
- 分类 - 从已有分类中选择（必选）
- 标签 - 添加标签，逗号分隔（可选）
- 草稿 - 是否保存为草稿（默认否）
自动生成 frontmatter（包含 title、date、categories、tags 等）
检查文件是否已存在，避免覆盖
文章保存在对应的分类目录下（如 src/content/blog/note/front-end/my-post.md）

新建友情链接功能：

交互式输入友链信息：
- 站点名称 - 友站的名称（必填）
- 站点 URL - 友站的链接（必填，需完整 URL）
- 站长昵称 - 友站站长的昵称（必填）
- 站点描述 - 友站的简介（必填）
- 头像 URL - 友站的头像链接（必填）
- 主题色 - 友站的主题色（可选，可选择预设颜色或自定义十六进制）
自动追加到 config/site.yaml 的 friends.data 数组
保留 YAML 文件的格式和注释

使用示例：

# 创建新文章
pnpm koharu new post
# 按提示输入：
# 标题: React Hooks 使用指南
# Slug: (自动生成 react-hooks-shi-yong-zhi-nan，可修改或清空)
# 描述: React Hooks 的完整使用教程
# 分类: 选择"笔记 → 前端"
# 标签: React, Hooks, 教程
# 草稿: 否

# 创建友链
pnpm koharu new friend
# 按提示输入友站信息

备份与还原

更新主题前，建议先备份你的个人内容：

# 基础备份（博客文章、配置、头像、.env）
pnpm koharu backup

# 完整备份（包含所有图片和生成的资产）
pnpm koharu backup --full

# 查看所有备份
pnpm koharu list

# 还原最新备份
pnpm koharu restore --latest

# 预览将要还原的文件（不实际还原）
pnpm koharu restore --dry-run

# 强制还原（覆盖已存在的文件）
pnpm koharu restore --force

# 清理旧备份（保留最近 5 个）
pnpm koharu clean --keep 5

备份文件存储在 backups/ 目录，格式为 backup-YYYY-MM-DD-HHMMSS.tar.gz。

更新主题

使用 CLI 自动更新主题，完成备份 → 拉取 → 合并 → 安装依赖的完整流程：

# 完整更新流程（默认会先备份）
pnpm koharu update

# 仅检查是否有更新
pnpm koharu update --check

# 跳过备份直接更新
pnpm koharu update --skip-backup

# 强制模式（跳过工作区检查和确认）
pnpm koharu update --force

# 更新到指定版本（如 v2.1.0）
pnpm koharu update --tag v2.1.0

# clean 模式（零冲突，强制备份，适合首次迁移或冲突较多时）
pnpm koharu update --clean

# rebase 模式（重写历史，强制备份，适合熟悉 git 的用户）
pnpm koharu update --rebase

# 预览操作（不实际执行，可配合 --clean 或 --rebase 使用）
pnpm koharu update --dry-run

选项说明：

选项	说明
`--check`	仅检查更新，不执行合并
`--skip-backup`	跳过备份步骤（clean/rebase 模式下无效，强制备份）
`--force`	跳过工作区脏检查和确认提示（不影响合并方式）
`--tag`	指定目标版本（如 `v2.1.0`），支持升级和降级
`--clean`	Clean 模式，零冲突更新（替换主题文件 + 还原用户内容）
`--rebase`	Rebase 模式，重写历史完全同步上游（强制要求备份）
`--dry-run`	预览操作，不实际执行

三种更新模式：

模式	命令	适合场景	备份	冲突处理
默认	`pnpm koharu update`	日常更新	可选	用户内容自动保留，主题冲突手动解决
Clean	`--clean`	首次迁移、冲突较多	强制	零冲突
Rebase	`--rebase`	熟悉 git 的用户	强制	需手动解决

默认模式（Merge）：

使用 git merge --no-ff 合并上游更新，保留 merge-base 信息，让后续更新的冲突更少。

智能冲突处理：

用户内容文件（博客文章、配置、独立页面、图片等）发生冲突时，自动保留本地版本
主题文件（组件、脚本、样式等）发生冲突时，需要手动解决
如果所有冲突都是用户内容 → 整个更新自动完成，零手动操作

提交格式：

chore: merge upstream theme v2.3.2

Clean 模式：

用上游最新版本替换所有主题文件，然后从备份还原用户内容，实现零冲突更新。

执行流程：

强制备份你的博客内容
创建 merge commit 记录版本关系
用上游文件覆盖本地所有文件
从刚才的备份还原用户内容（博客文章、配置、独立页面、图片、.env）

⚠️ 注意：

你对主题文件的自定义修改（如改了某个组件、布局、样式）不会被保留
备份范围包含：src/content/blog/、config/site.yaml、src/pages/*.md、public/img/、.env
使用 --full 备份选项可额外保留 favicon、LQIP、相似度、AI 摘要等生成资产

适用场景：

首次从旧版本迁移，历史冲突太多无法正常 merge
没有自定义主题文件，只写了博客内容

Rebase 模式：

执行 git rebase upstream/main（或指定的 tag），将本地提交重放到上游之上。适合熟悉 git 操作的用户。

⚠️ 注意：Rebase 模式会重写 Git 历史，请确保已备份重要内容。CLI 会强制要求备份（忽略 --skip-backup 和 --force）。

使用 --dry-run 预览：

所有模式都支持 --dry-run 预览操作效果：

pnpm koharu update --dry-run          # 预览默认 merge
pnpm koharu update --clean --dry-run  # 预览 clean 模式
pnpm koharu update --rebase --dry-run # 预览 rebase 操作

给熟悉 git 的用户： CLI 更新命令是对 git 操作的封装便利工具。如果你对 git 比较熟悉，建议直接使用 git fetch upstream && git rebase upstream/main 手动操作，这样能更精确地控制合并过程。

更新流程说明：

检查 Git 状态 — 确保工作区干净（无未提交的更改）
备份当前内容 — 可选（clean/rebase 模式强制备份）
设置 upstream — 自动添加 upstream remote（如果不存在）
获取最新代码 — git fetch upstream
显示更新预览 — 列出新增的提交和更新日志
执行更新 — 根据所选模式执行 merge / clean / rebase
安装依赖 — pnpm install

处理合并冲突：

默认 merge 模式下，用户内容冲突会被自动解决（保留本地版本）。如果主题文件仍有冲突，CLI 会显示冲突文件列表。你可以：

选择"中止合并"恢复到更新前状态
手动解决冲突后运行 git add . && git commit

# 如果选择手动解决冲突
git status                    # 查看冲突文件
# 编辑冲突文件，保留需要的内容
git add .
git commit -m "merge: resolve conflicts"

更新时使用的 Git 命令：

操作	命令
检查工作区状态	`git status --porcelain`
获取当前分支	`git rev-parse --abbrev-ref HEAD`
检查 upstream	`git remote -v`
添加 upstream	`git remote add upstream https://github.com/cosZone/astro-koharu.git`
获取更新	`git fetch upstream`
查看新提交数量	`git rev-list --left-right --count HEAD...upstream/main`
查看新提交列表	`git log HEAD..upstream/main --pretty=format:"%h \| %s \| %ar \| %an"`
默认合并	`git merge --no-ff upstream/main`
Clean 合并	`git merge -s ours upstream/main` + `git checkout upstream/main -- .`
Rebase	`git rebase upstream/main`
中止合并	`git merge --abort`

内容生成

生成各种内容资产：

# 交互式选择生成类型
pnpm koharu generate

# 或直接指定类型
pnpm koharu generate lqips        # 生成 LQIP 图片占位符
pnpm koharu generate similarities # 生成语义相似度向量
pnpm koharu generate summaries    # 生成 AI 摘要
pnpm koharu generate all          # 生成全部

如何添加新页面

在 src/pages/ 目录创建 .astro 文件
Astro 使用文件系统路由，文件路径即 URL 路径

示例：

src/pages/about.astro       → /about
src/pages/tags/[tag].astro  → /tags/:tag（动态路由）

如何自定义样式

全局样式：

编辑 src/styles/index.css。

组件样式：

使用 Tailwind CSS 工具类或 Astro 的 <style> 标签。

Tailwind 配置：

编辑 tailwind.config.ts 自定义主题、颜色、字体等。

主题变量：

在 src/styles/index.css 中定义的 CSS 变量：

:root {
  --primary-color: #ff6b6b;
  /* ... 更多变量 */
}

动画系统

使用 CSS 动画以及 Motion。

动画配置：

在 src/constants/anim/ 目录中：

spring.ts - 弹簧动画配置
variants.ts - 动画变体定义
props.ts - 可复用的动画属性

使用示例：

import { motion } from "motion/react";
import { fadeIn } from "@constants/anim/variants";

<motion.div variants={fadeIn} initial="hidden" animate="visible">
  内容
</motion.div>;

与 Hexo/Shoka 主题的对比

保留的特性

✅ 分类和标签系统
✅ 文章置顶功能
✅ 深色/浅色主题切换
✅ 响应式设计
✅ 友链页面
✅ 归档页面

改进之处

性能：

⚡ 静态站点生成 (SSG)，加载速度更快
⚡ 按需加载 JavaScript
⚡ 图片优化

开发体验：

️ TypeScript 类型安全
️ 热模块替换 (HMR)
️ 现代化的开发工具链

功能增强：

更强大的全站搜索（Pagefind）
内容集合 (Content Collections) 类型安全
Tailwind CSS 4.x 样式系统
View Transitions API 页面过渡

技术栈差异

方面	Hexo + Shoka	astro-koharu
框架	Hexo (Node.js)	Astro 5.x
模板引擎	EJS/Pug	Astro + React
样式	Stylus	Tailwind CSS 4.x
构建工具	Webpack	Vite
类型检查	无	TypeScript
内容管理	文件系统	Content Collections

常见问题

如何修改封面图片？

在文章 frontmatter 中设置 cover 字段：

cover: /img/cover/1.webp

图片放在 public/img/ 目录。如果不设置，会使用默认封面。

如何自定义域名？

部署到 Vercel 后，在 Vercel 项目设置中添加自定义域名，然后更新 config/site.yaml 中的 site.url 字段。

如何添加评论功能？

项目支持三种评论系统：Waline、Giscus、Remark42。在 config/site.yaml 的 comment 配置块中选择使用的提供商。

Waline（推荐）

Waline 是一个简洁、安全的评论系统，支持多种部署方式（Vercel、Railway、Zeabur 等）。

特点：

部署简单，支持多种平台一键部署
支持 Markdown、表情、@提及、邮件通知
内置浏览量统计、评论管理后台
支持多种登录方式（匿名、社交账号）
️ 内置反垃圾评论、敏感词过滤
自动跟随站点深色/浅色主题

前置要求：

部署 Waline 服务端（部署指南）
获取服务端 URL

配置示例：

comment:
  provider: waline
  waline:
    serverURL: https://your-waline-server.vercel.app # Waline 服务端地址（必填）
    lang: zh-CN # 语言
    dark: html.dark # 暗黑模式 CSS 选择器
    meta: # 评论者信息字段
      - nick
      - mail
      - link
    requiredMeta: # 必填字段
      - nick
    login: enable # 登录模式 ('enable' | 'disable' | 'force')
    wordLimit: 0 # 评论字数限制 (0 = 无限制)
    pageSize: 10 # 每页评论数
    imageUploader: false # 图片上传功能
    highlighter: true # 代码高亮
    texRenderer: false # LaTeX 渲染
    search: false # 搜索功能
    reaction: false # 文章反应功能
    # recaptchaV3Key: '' # reCAPTCHA v3 Key (可选)
    # turnstileKey: '' # Cloudflare Turnstile Key (可选)

参数说明：

参数	类型	默认值	说明
`serverURL`	`string`	必填	Waline 服务端地址
`lang`	`string`	`'zh-CN'`	界面语言（支持 zh-CN, en, jp 等）
`dark`	`string`	`'html.dark'`	暗黑模式 CSS 选择器
`meta`	`string[]`	`['nick','mail','link']`	评论者信息字段
`requiredMeta`	`string[]`	`['nick']`	必填字段
`login`	`'enable'` \| `'disable'` \| `'force'`	`'enable'`	登录模式
`wordLimit`	`number`	`0`	评论字数限制（0 = 无限制）
`pageSize`	`number`	`10`	每页评论数
`imageUploader`	`boolean`	`false`	是否启用图片上传
`highlighter`	`boolean`	`true`	是否启用代码高亮
`texRenderer`	`boolean`	`false`	是否启用 LaTeX 渲染
`search`	`boolean`	`false`	是否启用搜索功能
`reaction`	`boolean`	`false`	是否启用文章反应功能
`recaptchaV3Key`	`string`	-	reCAPTCHA v3 Key（可选，防垃圾评论）
`turnstileKey`	`string`	-	Cloudflare Turnstile Key（可选）

部署 Waline 服务端：

推荐使用 Vercel 一键部署：

访问 Waline 快速开始
点击 "Deploy with Vercel" 按钮
登录 Vercel，授权 GitHub 仓库
配置环境变量（数据库连接、管理员邮箱等）
部署完成后获取服务端 URL（如 https://your-waline.vercel.app）

主题自动切换：

Waline 组件已实现主题自动切换，通过 dark 参数（默认 html.dark）自动跟随站点深色/浅色模式。

参考链接：

Remark42

Remark42 是一个轻量级的自托管评论系统，隐私友好，无需第三方服务。

特点：

自托管，完全掌控数据
无广告、无追踪
支持多种存储后端（BoltDB、Memory）
支持多种社交登录（GitHub、Google、Twitter 等）
邮件通知、评论审核
自动跟随站点深色/浅色主题

前置要求：

部署 Remark42 服务端（部署指南）
配置站点 ID 和域名

配置示例：

comment:
  provider: remark42
  remark42:
    host: https://comment.example.com/ # Remark42 服务器地址（必填）
    siteId: your-site-id # 站点 ID（必填）

参数说明：

参数	类型	说明
`host`	`string`	Remark42 服务器地址（必填，需带 `http://` 或 `https://`）
`siteId`	`string`	站点 ID（必填，在 Remark42 服务端配置中定义）

部署 Remark42 服务端：

推荐使用 Docker 部署：

docker run -d \
  --name remark42 \
  -p 8080:8080 \
  -e REMARK_URL=https://comment.example.com \
  -e SECRET=your-secret-key \
  -e SITE=your-site-id \
  -e AUTH_GITHUB_CID=your-github-client-id \
  -e AUTH_GITHUB_CSEC=your-github-client-secret \
  -v /path/to/data:/srv/var \
  umputun/remark42:latest

详细配置请参考 Remark42 安装指南。

主题自动切换：

Remark42 组件已实现主题自动切换，使用 MutationObserver 监听站点主题变化，自动调用 window.REMARK42.changeTheme() 更新评论框主题。

参考链接：

Giscus

Giscus 是基于 GitHub Discussions 的评论系统，无需自建后端，评论数据存储在你的 GitHub 仓库中。

具体配置可以看看这篇文章：https://zhuanlan.zhihu.com/p/693434928

前置要求：

仓库必须是公开的
安装 giscus app
在仓库中启用 Discussions 功能

获取配置参数：

访问 giscus.app
输入你的仓库名称（格式：owner/repo）
选择页面与 Discussion 的映射方式（推荐 pathname）
选择 Discussion 分类（推荐 Announcements）
启用所需功能（reactions、评论框位置等）
复制生成的 data-repo-id 和 data-category-id

配置示例：

comment:
  provider: giscus
  giscus:
    repo: username/repo # GitHub 仓库名 (owner/repo 格式)
    repoId: R_kgDOxxxxxx # 仓库 ID (从 giscus.app 获取)
    category: Announcements # Discussion 分类名称
    categoryId: DIC_kwDOxxxxxx # 分类 ID (从 giscus.app 获取)
    mapping: pathname # 映射方式
    reactionsEnabled: "1" # 启用 reactions ('1' 启用, '0' 禁用)
    emitMetadata: "0" # 发送元数据
    inputPosition: top # 输入框位置 ('top' | 'bottom')
    lang: zh-CN # 语言

参数说明：

参数	类型	说明
`repo`	`string`	GitHub 仓库，格式为 `owner/repo`
`repoId`	`string`	仓库 ID，从 giscus.app 获取
`category`	`string`	Discussion 分类名称
`categoryId`	`string`	分类 ID，从 giscus.app 获取
`mapping`	`string`	页面与 Discussion 的映射方式
`term`	`string`	当 `mapping` 为 `specific` 或 `number` 时使用
`strict`	`'0' \| '1'`	严格匹配模式，默认 `'0'`
`reactionsEnabled`	`'0' \| '1'`	是否启用 reactions，默认 `'1'`
`emitMetadata`	`'0' \| '1'`	是否发送页面元数据，默认 `'0'`
`inputPosition`	`'top' \| 'bottom'`	评论输入框位置，默认 `'top'`
`lang`	`string`	界面语言，默认 `'zh-CN'`
`host`	`string`	自托管 Giscus 实例的地址（可选）
`theme`	`string`	固定主题（不设置则跟随站点主题切换）
`loading`	`'lazy' \| 'eager'`	加载方式，默认 `'lazy'`

映射方式说明：

pathname（推荐）：使用页面路径匹配，如 /post/my-article
url：使用完整 URL 匹配
title：使用页面标题匹配
og:title：使用 Open Graph 标题匹配
specific：使用 term 参数指定的值
number：使用 term 参数指定的 Discussion 编号

主题自动切换：

本主题已实现 Giscus 评论框的主题自动切换，会跟随站点的深色/浅色模式自动调整。实现原理：

组件挂载时读取当前主题
使用 MutationObserver 监听 document.documentElement 的 class 变化
检测到主题切换时通过 postMessage 通知 Giscus iframe 更新主题

参考链接：

草稿文章如何预览？

运行 pnpm dev 本地开发模式，草稿会自动显示（带 DRAFT 标识）。

如何关闭某些功能？

关闭某个系列：设置该系列的 enabled: false

featuredSeries:
  - slug: weekly
    enabled: false # 禁用此系列
    # ...

关闭所有系列：将 featuredSeries 设为空数组 []
关闭搜索：移除 astro.config.mjs 中的 pagefind() 集成
关闭统计：设置 analytics.umami.enabled = false
关闭评论：移除 comment.provider 配置或将其设置为空
关闭 Shoka 语法：在 config/site.yaml 的 content 部分将对应功能设为 false，如 enableShokaContainers: false（关闭提醒块/折叠块/标签卡）、enableShokaSpoiler: false（关闭隐藏文字）等
关闭数学公式：设置 content.enableMath = false
关闭练习题：设置 content.enableQuiz = false

如何更改文章 URL 格式？

默认使用文件名作为 URL。可以通过 link 字段自定义：

link: my-custom-url

URL 特殊字符处理

文章链接（link）和标签（tags）支持包含特殊字符，系统会自动进行 URL 编码处理。

文章链接特殊字符：

---
title: C# 学习笔记
link: test-C# # 包含 # 字符
---

访问时 URL 会自动编码为 /post/test-C%23，确保浏览器正确解析。

标签特殊字符：

tags:
  - C#
  - C++
  - .NET
  - Node.js

标签会自动转换为 URL 安全的格式：

C# → /tags/c%23
C++ → /tags/c%2B%2B
.NET → /tags/.net
Node.js → /tags/node.js

注意事项：

特殊字符包括：#、+、&、?、%、空格等
标签中的 / 会被替换为 -（如 前端/React → 前端-react）
分类名称通过 categoryMap 映射，建议使用纯英文 slug 避免编码问题

参考资源

更新日志

查看 CHANGELOG.md 了解版本更新历史。

如有问题或建议，欢迎在 GitHub Issues 中反馈。

为 Astro 博客添加可插拔的圣诞特效模块

Wed, 24 Dec 2025 17:11:00 GMT

本文由 AI 辅助写作，作记录用

圣诞节到了，想给博客加点节日氛围。最终实现了一套可插拔的圣诞特效模块，包括：

3D 雪花飘落（React Three Fiber + GLSL 着色器）
悬挂彩灯装饰（CSS 动画）
头像圣诞帽（SVG）
圣诞配色方案（CSS 变量）
可拖拽圣诞球开关

先放最终效果：

如果嫌弃干扰阅读了，可以点击开关关掉～

注意看这个雪是双层的，内容容器夹在雪花中间，远景雪花在文章后面飘过，近景雪花在前面飘过，配合视差效果，感觉还挺满意的。

技术选型上，雪花飘落使用 React Three Fiber 实现 GPU 着色器驱动 的 6 层粒子系统，支持鼠标视差效果，在视觉效果和性能之间取得平衡。

整体架构

flowchart TB
    subgraph Config[配置层]
        SC[site-config.ts<br/>christmasConfig]
    end

    subgraph State[状态管理]
        NS[nanostores<br/>christmasEnabled]
        LS[localStorage<br/>持久化]
    end

    subgraph Effects[特效组件]
        SF[SnowfallCanvas<br/>GLSL 雪花着色器]
        CL[ChristmasLights<br/>CSS 彩灯]
        CH[ChristmasHat<br/>SVG 圣诞帽]
        CT[christmas-theme.css<br/>配色方案]
    end

    subgraph UI[用户界面]
        OT[ChristmasOrnamentToggle<br/>可拖拽开关]
    end

    SC --> NS
    NS <--> LS
    NS --> SF
    SC --> CL
    OT --> NS
    SC --> CH
    SC --> CT

所有特效都通过 christmasConfig.enabled 控制，运行时状态通过 nanostores 管理，支持用户手动切换并持久化到 localStorage。

配置结构设计

在 src/constants/site-config.ts 中定义圣诞配置：

type ChristmasConfig = {
  enabled: boolean;
  features: {
    snowfall: boolean;             // 雪花飘落
    christmasColorScheme: boolean; // 圣诞配色
    christmasCoverDecoration: boolean; // Cover 彩灯装饰
    christmasHat: boolean;         // 头像圣诞帽
  };
  snowfall: {
    speed: number;                 // 下落速度 (1 = 正常)
    intensity: number;             // 雪花密度 (0-1)
    mobileIntensity: number;       // 移动端密度 (0-1)
  };
};

export const christmasConfig: ChristmasConfig = {
  enabled: true,
  features: {
    snowfall: true,
    christmasColorScheme: true,
    christmasCoverDecoration: true,
    christmasHat: true,
  },
  snowfall: {
    speed: 1,
    intensity: 0.6,
    mobileIntensity: 0.4,
  },
};

这种设计允许细粒度控制各个特效，方便调试和按需启用。

状态管理：跨 Astro/React 边界

Astro 的岛屿架构中，.astro 组件和 React 组件需要共享状态。使用 nanostores 作为轻量级状态管理：

// src/store/christmas.ts
import { atom } from 'nanostores';

const STORAGE_KEY = 'christmas-enabled';

// 运行时开关状态
export const christmasEnabled = atom<boolean>(true);

// 初始化：从 localStorage 恢复状态
export function initChristmasState(): void {
  if (typeof window === 'undefined') return;

  const stored = localStorage.getItem(STORAGE_KEY);
  if (stored !== null) {
    christmasEnabled.set(stored === 'true');
  }
  syncChristmasClass(christmasEnabled.get());
}

// 同步 html.christmas class（用于 CSS 配色切换）
function syncChristmasClass(enabled: boolean): void {
  if (typeof document === 'undefined') return;
  document.documentElement.classList.toggle('christmas', enabled);
}

// 切换开关
export function toggleChristmas(): void {
  const newValue = !christmasEnabled.get();
  christmasEnabled.set(newValue);
  localStorage.setItem(STORAGE_KEY, String(newValue));
  syncChristmasClass(newValue);
}

// 启用圣诞特效
export function enableChristmas(): void {
  christmasEnabled.set(true);
  localStorage.setItem(STORAGE_KEY, 'true');
  syncChristmasClass(true);
}

// 禁用圣诞特效
export function disableChristmas(): void {
  christmasEnabled.set(false);
  localStorage.setItem(STORAGE_KEY, 'false');
  syncChristmasClass(false);
}

在 React 组件中使用 @nanostores/react 的 useStore 订阅状态：

import { useStore } from '@nanostores/react';
import { christmasEnabled } from '@store/christmas';

function SnowfallCanvas() {
  const isEnabled = useStore(christmasEnabled);

  if (!isEnabled) return null;
  // ...渲染雪花
}

在 Astro 组件的 <script> 中直接使用：

import { christmasEnabled, toggleChristmas } from '@store/christmas';

christmasEnabled.subscribe((enabled) => {
  // 更新 UI 状态
});

雪花飘落：React Three Fiber 粒子系统

选择 React Three Fiber + 自定义 GLSL 着色器，参考 Shadertoy 上的 “Just snow” 效果，完全在 GPU 上计算和渲染 6 层雪花。

粒子系统实现

使用 ShaderMaterial 实现全屏着色器渲染：

// src/components/christmas/SnowParticles.tsx
import { useFrame, useThree } from '@react-three/fiber';
import { useMemo, useRef, type MutableRefObject } from 'react';
import * as THREE from 'three';

const SnowShaderMaterial = {
  vertexShader: `
    varying vec2 vUv;
    void main() {
      vUv = uv;
      gl_Position = vec4(position, 1.0);
    }
  `,
  fragmentShader: `
    uniform float uTime;
    uniform vec2 uResolution;
    uniform float uSpeed;
    uniform float uIntensity;
    uniform vec2 uMouse;      // 鼠标视差偏移
    uniform int uLayerStart;  // 渲染层范围起始
    uniform int uLayerEnd;    // 渲染层范围结束

    varying vec2 vUv;

    void main() {
      vec2 fragCoord = vUv * uResolution;
      float snow = 0.0;
      float time = uTime * uSpeed;

      // 6层雪花，每层12次迭代
      for(int k = 0; k < 6; k++) {
        if(k < uLayerStart || k > uLayerEnd) continue;
        for(int i = 0; i < 12; i++) {
          float cellSize = 2.0 + (float(i) * 3.0);
          float downSpeed = 0.3 + (sin(time * 0.4 + float(k + i * 20)) + 1.0) * 0.00008;

          // 视差偏移：近景层偏移更多
          float parallaxFactor = 0.5 + float(k) * 0.1;
          vec2 mouseOffset = uMouse * parallaxFactor;

          vec2 uv = (fragCoord.xy / uResolution.x) + mouseOffset + vec2(
            0.01 * sin((time + float(k * 6185)) * 0.6 + float(i)) * (5.0 / float(i)),
            downSpeed * (time + float(k * 1352)) * (1.0 / float(i))
          );

          vec2 uvStep = (ceil((uv) * cellSize - vec2(0.5, 0.5)) / cellSize);
          float x = fract(sin(dot(uvStep.xy, vec2(12.9898 + float(k) * 12.0, 78.233 + float(k) * 315.156))) * 43758.5453 + float(k) * 12.0) - 0.5;
          float y = fract(sin(dot(uvStep.xy, vec2(62.2364 + float(k) * 23.0, 94.674 + float(k) * 95.0))) * 62159.8432 + float(k) * 12.0) - 0.5;

          float d = 5.0 * distance((uvStep.xy + vec2(x * sin(y), y) * sin(time * 2.5) * 0.7 / cellSize), uv.xy);

          float omiVal = fract(sin(dot(uvStep.xy, vec2(32.4691, 94.615))) * 31572.1684);
          if(omiVal < 0.08) {
            snow += (x + 1.0) * 0.4 * clamp(1.9 - d * (15.0 + (x * 6.3)) * (cellSize / 1.4), 0.0, 1.0);
          }
        }
      }

      gl_FragColor = vec4(1.0, 1.0, 1.0, snow * uIntensity);
    }
  `,
};

interface SnowParticlesProps {
  speed?: number;
  intensity?: number;
  parallaxRef?: MutableRefObject<{ x: number; y: number }>;
  layerRange?: [number, number];
}

export function SnowParticles({
  speed = 1,
  intensity = 0.6,
  parallaxRef,
  layerRange = [0, 5]
}: SnowParticlesProps) {
  const shaderMaterial = useRef<THREE.ShaderMaterial>(null);
  const { size } = useThree();
  const [layerStart, layerEnd] = layerRange;

  const uniforms = useMemo(() => ({
    uTime: { value: 0 },
    uResolution: { value: new THREE.Vector2(size.width, size.height) },
    uSpeed: { value: speed },
    uIntensity: { value: intensity },
    uMouse: { value: new THREE.Vector2(0, 0) },
    uLayerStart: { value: layerStart },
    uLayerEnd: { value: layerEnd },
  }), [size.width, size.height, speed, intensity, layerStart, layerEnd]);

  useFrame((state) => {
    if (shaderMaterial.current) {
      shaderMaterial.current.uniforms.uTime.value = state.clock.getElapsedTime();
      if (parallaxRef) {
        shaderMaterial.current.uniforms.uMouse.value.set(parallaxRef.current.x, parallaxRef.current.y);
      }
    }
  });

  return (
    <mesh>
      <planeGeometry args={[2, 2]} />
      <shaderMaterial
        ref={shaderMaterial}
        transparent
        depthWrite={false}
        blending={THREE.AdditiveBlending}
        uniforms={uniforms}
        vertexShader={SnowShaderMaterial.vertexShader}
        fragmentShader={SnowShaderMaterial.fragmentShader}
      />
    </mesh>
  );
}

核心思路：

使用 planeGeometry 创建全屏四边形
Fragment Shader 中用 6 层嵌套循环生成不同大小、速度的雪花
每层雪花有独立的下落速度和风力相位
通过 uLayerStart 和 uLayerEnd uniform 控制渲染哪些层（用于前后景分离）

Canvas 配置：不阻挡点击

一个关键问题是 R3F Canvas 默认会拦截所有鼠标事件，导致下方元素无法点击。解决方案：

<Canvas
  // 全屏着色器使用正交相机
  orthographic
  camera={{ zoom: 1, position: [0, 0, 1] }}
  // 禁用 R3F 的事件系统
  eventSource={undefined}
  eventPrefix={undefined}
  style={{ pointerEvents: 'none' }}
  gl={{
    antialias: false,
    alpha: true,
    powerPreference: 'low-power', // 省电模式
  }}
  dpr={[1, 1.5]} // 限制 DPR，移动端性能优化
>

鼠标视差效果

参考 Shadertoy 上的 “Just snow” 效果，添加鼠标移动时的视差偏移，让雪花更有层次感。

核心思路：

使用 Motion 的 useMotionValue + useSpring 追踪并平滑鼠标位置
将平滑后的值传递给着色器的 uMouse uniform
着色器中不同层使用不同的视差因子，近景层偏移更多

// SnowfallCanvas.tsx - 鼠标追踪
const mouseX = useMotionValue(0);
const mouseY = useMotionValue(0);
const smoothMouseX = useSpring(mouseX, { stiffness: 50, damping: 20 });
const smoothMouseY = useSpring(mouseY, { stiffness: 50, damping: 20 });

useEffect(() => {
  if (isMobile) return; // 移动端无鼠标

  const handleMouseMove = (e: MouseEvent) => {
    // 标准化到 -0.5 ~ 0.5
    mouseX.set(e.clientX / window.innerWidth - 0.5);
    mouseY.set(e.clientY / window.innerHeight - 0.5);
  };

  const handleMouseLeave = () => {
    // 鼠标离开窗口时回到中心
    mouseX.set(0);
    mouseY.set(0);
  };

  window.addEventListener('mousemove', handleMouseMove, { passive: true });
  document.addEventListener('mouseleave', handleMouseLeave);
  return () => {
    window.removeEventListener('mousemove', handleMouseMove);
    document.removeEventListener('mouseleave', handleMouseLeave);
  };
}, [isMobile]);

着色器中应用视差：

uniform vec2 uMouse;

// 在每层雪花的 UV 计算中
float parallaxFactor = 0.5 + float(k) * 0.1; // k=0~5 → 0.5~1.0
vec2 mouseOffset = uMouse * parallaxFactor;
vec2 uv = (fragCoord.xy / uResolution.x) + mouseOffset + ...;

由于 Motion 的 spring 值在 React 渲染循环外更新，而 R3F 的 useFrame 也在外部运行，需要用桥接组件订阅 spring 变化并存入 ref：

function SnowParticlesWithParallax({
  speed,
  intensity,
  smoothMouseX,
  smoothMouseY,
  parallaxStrength,
  layerRange,
}: {
  speed: number;
  intensity: number;
  smoothMouseX: MotionValue<number>;
  smoothMouseY: MotionValue<number>;
  parallaxStrength: number;
  layerRange: [number, number];
}) {
  const parallaxRef = useRef({ x: 0, y: 0 });

  useEffect(() => {
    const unsubX = smoothMouseX.on('change', (v) => {
      parallaxRef.current.x = v * parallaxStrength;
    });
    const unsubY = smoothMouseY.on('change', (v) => {
      parallaxRef.current.y = v * parallaxStrength;
    });
    return () => { unsubX(); unsubY(); };
  }, [smoothMouseX, smoothMouseY, parallaxStrength]);

  return <SnowParticles speed={speed} intensity={intensity} parallaxRef={parallaxRef} layerRange={layerRange} />;
}

双层渲染：前景与背景分离

为了让雪花更有层次感，将 6 层雪花分成两组渲染到不同的 z-index：

层级	z-index	着色器层 (k)	效果
背景雪	1	k=0-2	远景、小雪花、视差弱
内容	正常文档流	-	文章容器
前景雪	50	k=3-5	近景、大雪花、视差强

实现方式是给 SnowParticles 添加 layerRange prop，着色器中根据范围跳过不需要的层：

uniform int uLayerStart;
uniform int uLayerEnd;

for(int k = 0; k < 6; k++) {
  if(k < uLayerStart || k > uLayerEnd) continue;
  // ... 原有雪花渲染逻辑
}

然后渲染两个 Canvas：

{/* 背景雪 */}
<SnowfallCanvas zIndex={1} layerRange={[0, 2]} />
{/* 前景雪 */}
<SnowfallCanvas zIndex={50} layerRange={[3, 5]} />

这样内容容器就”夹”在雪花中间，远景雪花在文章后面飘过，近景雪花在前面飘过，配合视差效果产生很好的深度感。

圣诞彩灯：CSS 动画

在 Cover 顶部添加悬挂式彩灯装饰，参考 Toby J 的 CodePen 实现，调整为圣诞配色（红、绿、金）。

实现原理

彩灯效果完全使用 CSS 实现：

灯泡使用 border-radius: 50% 创建椭圆形
灯座使用 ::before 伪元素
电线使用 ::after 伪元素的 border-bottom + border-radius 模拟弧形
闪烁效果使用 @keyframes 动画改变 background 和 box-shadow

---
// src/components/christmas/ChristmasLights.astro
// 生成足够数量的灯泡覆盖最大屏幕宽度
const lightCount = 50;
---

<ul class="lightrope" aria-hidden="true">
  {Array.from({ length: lightCount }).map(() => <li />)}
</ul>

<style>
  .lightrope {
    --globe-width: 12px;
    --globe-height: 28px;
    --globe-spacing: 40px;
    --globe-spread: 3px;
    --light-off-opacity: 0.4;

    /* 圣诞配色 */
    --light-red: 185, 50, 50;
    --light-green: 34, 139, 34;
    --light-gold: 218, 165, 32;

    position: fixed;
    top: 42px;
    left: 0;
    z-index: 100;
    width: 100%;
    pointer-events: none;
  }

  .lightrope li {
    display: inline-block;
    width: var(--globe-width);
    height: var(--globe-height);
    margin: calc(var(--globe-spacing) / 2);
    border-radius: 50%;
    background: rgb(var(--light-red));
    box-shadow: 0px 4px 24px 3px rgba(var(--light-red), 1);
    animation: flash-red 2s ease-in-out infinite;
  }

  /* 绿色灯泡 - 每隔一个 */
  .lightrope li:nth-child(2n + 1) {
    background: rgb(var(--light-green));
    animation-name: flash-green;
    animation-duration: 0.4s;
  }

  /* 金色灯泡 - 每 4 个中的第 2 个 */
  .lightrope li:nth-child(4n + 2) {
    background: rgb(var(--light-gold));
    animation-name: flash-gold;
    animation-duration: 1.1s;
  }

  /* 灯座 */
  .lightrope li::before {
    content: '';
    position: absolute;
    top: -5px;
    width: 10px;
    height: 9px;
    background: hsl(var(--background) / 0.6);
    border-radius: 3px;
  }

  /* 连接电线 */
  .lightrope li::after {
    content: '';
    position: absolute;
    top: -14px;
    left: 9px;
    width: 52px;
    height: 18px;
    border-bottom: solid hsl(var(--background) / 0.6) 2px;
    border-radius: 50%;
  }

  /* 闪烁动画 */
  @keyframes flash-red {
    0%,
    100% {
      background: rgb(var(--light-red));
      box-shadow: 0px 4px 24px 3px rgba(var(--light-red), 1);
    }
    50% {
      background: rgba(var(--light-red), 0.4);
      box-shadow: 0px 4px 24px 3px rgba(var(--light-red), 0.2);
    }
  }

  /* 无障碍：减少动画 */
  @media (prefers-reduced-motion: reduce) {
    .lightrope li {
      animation: none;
    }
  }
</style>

在 Cover 中使用

// src/components/ui/cover/Cover.astro
+ import { christmasConfig } from '@constants/site-config';
+ import ChristmasLights from '@components/christmas/ChristmasLights.astro';

<div class="relative flex h-[60dvh] max-h-200 overflow-hidden">
+ {christmasConfig.enabled && christmasConfig.features.christmasCoverDecoration && <ChristmasLights />}
  <div class="absolute inset-0 h-full bg-black/40"></div>
  ...
</div>

彩灯使用 position: fixed 固定在视口顶部，z-index: 100 确保显示在导航栏之上。电线和灯座颜色使用 hsl(var(--background) / 0.6) 自动适配亮暗主题。

彩灯性能优化

初版彩灯使用 box-shadow 动画实现闪烁效果，但存在严重性能问题：

50 个元素使用 will-change: box-shadow, background：创建过多合成层，占用大量内存
box-shadow 动画触发 paint：每帧都需要重绘，CPU 开销大
动画持续运行：即使 Tab 不可见或圣诞模式关闭，动画仍在消耗资源

优化方案：

<script>
  function initLightsVisibility() {
    // Tab 可见性检测 - 不可见时暂停动画
    const handleVisibility = () => {
      document.documentElement.classList.toggle('lights-paused', document.hidden);
    };
    handleVisibility();
    document.addEventListener('visibilitychange', handleVisibility);
  }

  if (document.readyState !== 'loading') initLightsVisibility();
  document.addEventListener('astro:page-load', initLightsVisibility);
</script>

<style>
  .lightrope li {
    /* 静态 box-shadow - 不参与动画 */
    box-shadow:
      0px 4px 24px 6px rgba(var(--light-red), 1),
      0px 2px 8px 2px rgba(var(--light-red), 0.6);
    /* 仅使用 opacity + scale 动画 - GPU 合成，无 paint 开销 */
    animation: flash-bulb 1.2s ease-in-out infinite;
  }

  /* 流水灯效果 - 每 6 个灯泡一组 */
  .lightrope li:nth-child(6n + 1) { animation-delay: 0s; }
  .lightrope li:nth-child(6n + 2) { animation-delay: 0.15s; }
  .lightrope li:nth-child(6n + 3) { animation-delay: 0.3s; }
  .lightrope li:nth-child(6n + 4) { animation-delay: 0.45s; }
  .lightrope li:nth-child(6n + 5) { animation-delay: 0.6s; }
  .lightrope li:nth-child(6n) { animation-delay: 0.75s; }

  @keyframes flash-bulb {
    0%, 100% {
      opacity: 1;
      transform: scale(1);
    }
    50% {
      opacity: 0.4;
      transform: scale(0.9);
    }
  }

  /* Tab 不可见时暂停 */
  :global(html.lights-paused) .lightrope li {
    animation-play-state: paused;
  }

  /* 圣诞模式关闭时暂停 */
  :global(html:not(.christmas)) .lightrope li {
    animation-play-state: paused;
  }
</style>

核心优化点：

优化项	之前	之后
动画属性	`box-shadow` + `background` (触发 paint)	`opacity` + `transform: scale()` (GPU 合成)
合成层	50+ (`will-change`)	自动管理
Tab 不可见	持续运行	暂停
圣诞模式关闭	持续运行 (仅隐藏)	暂停
视觉效果	随机闪烁	流水灯 + 缩放

另外将配色升级为四色方案（红、绿、金、蓝），发光效果使用双层 box-shadow 增强，动画周期缩短到 1.2s 让节奏更活泼。

圣诞帽：SVG 绘制

头像上的圣诞帽使用纯 SVG 绘制，支持自定义尺寸、位置、旋转角度和颜色：

---
interface Props {
  className?: string;
  size?: number | string;
  offset?: { x?: number; y?: number };
  rotate?: number;
  colors?: {
    primary?: string;
    secondary?: string;
    white?: string;
  };
}

const {
  className,
  size = '100%',
  offset = { x: -28, y: -50 },
  rotate = 10,
  colors = {
    primary: '#FF4E50',
    secondary: '#C00000',
    white: '#FFFFFF',
  },
} = Astro.props;

// 生成唯一 ID 避免多个帽子时 gradient 冲突
const uniqueId = Math.random().toString(36).substring(2, 9);
---

<div
  class:list={['christmas-hat-wrapper', className]}
  style={{
    width: typeof size === 'number' ? `${size}px` : size,
    height: typeof size === 'number' ? `${size}px` : size,
    top: `${offset.y}%`,
    left: `${offset.x}%`,
    transform: `rotate(${rotate}deg)`,
  }}
>
  <svg viewBox="0 0 200 200" fill="none">
    <defs>
      <linearGradient id={`hatGradient_${uniqueId}`} ...>
        <stop stop-color={colors.primary}></stop>
        <stop offset="1" stop-color={colors.secondary}></stop>
      </linearGradient>
    </defs>
    <!-- 帽身 -->
    <path d="M179.712 87.522 ..." fill={`url(#hatGradient_${uniqueId})`}></path>
    <!-- 白边 -->
    <path d="M181.512 88.5738 ..." stroke={colors.white} stroke-width="28"></path>
    <!-- 毛球 -->
    <circle cx="38.5" cy="144.5" r="19.5" fill={colors.white}></circle>
  </svg>
</div>

<style>
  .christmas-hat-wrapper {
    position: absolute;
    pointer-events: none;
    z-index: 20;
    transition: transform 0.3s ease;
    filter: drop-shadow(0px 10px 15px rgba(0, 0, 0, 0.1));
  }
</style>

通过 props 可以灵活调整帽子的位置和样式，适配不同尺寸的头像。使用 linearGradient 实现帽身的渐变效果，drop-shadow 添加阴影增加立体感。

圣诞配色方案

通过 CSS 自定义属性实现主题切换，当 <html> 有 .christmas 类时激活：

/* src/styles/christmas/christmas-theme.css */
.christmas {
  --christmas-red: 0 70% 45%;
  --christmas-green: 150 60% 35%;
  --christmas-gold: 43 75% 55%;

  /* 覆盖主色调 */
  --primary: var(--christmas-red);
}

.christmas.dark {
  --christmas-red: 0 65% 55%;
  --gradient-bg-start: #1a1512;
  --gradient-bg-end: #0d1a0d;
}

在 Layout 中根据配置添加类名：

<html class:list={[{ christmas: christmasConfig.enabled && christmasConfig.features.christmasColorScheme }]}></html>

开关按钮

在悬浮按钮组中添加圣诞开关：

{
  christmasConfig.enabled && (
    <button id="toggle-christmas" class="rounded-full p-2 shadow-lg backdrop-blur-sm" aria-label="切换圣诞特效">
      <Icon name="ri:snowy-fill" class="christmas-on h-5 w-5" />
      <Icon name="ri:snowy-line" class="christmas-off hidden h-5 w-5" />
    </button>
  )
}

<script>
  import { christmasEnabled, toggleChristmas, initChristmasState } from '@store/christmas';

  function init() {
    initChristmasState();

    const btn = document.getElementById('toggle-christmas');
    btn?.addEventListener('click', () => {
      toggleChristmas();
    });

    // 订阅状态变化，更新按钮图标
    christmasEnabled.subscribe((enabled) => {
      const onIcon = btn?.querySelector('.christmas-on');
      const offIcon = btn?.querySelector('.christmas-off');
      onIcon?.classList.toggle('hidden', !enabled);
      offIcon?.classList.toggle('hidden', enabled);
    });
  }

  document.addEventListener('astro:page-load', init);
</script>

圣诞球开关：可拖拽的装饰组件

除了简单的图标按钮，还实现了一个更有趣的交互方式：悬挂在页面右上角的圣诞球装饰，支持拖拽下拉触发开关。

实现原理

使用 Motion 的 drag API 实现拖拽交互：

useMotionValue 追踪拖拽位置
useTransform 派生绳子高度
dragSnapToOrigin 自动回弹
拖拽超过阈值时触发状态切换

// src/components/christmas/ChristmasOrnamentToggle.tsx
import { cn } from '@lib/utils';
import { useStore } from '@nanostores/react';
import { christmasEnabled, disableChristmas, toggleChristmas } from '@store/christmas';
import { AnimatePresence, motion, useMotionValue, useReducedMotion, useTransform } from 'motion/react';
import { useState } from 'react';

const DRAG_THRESHOLD = 80;
const ORNAMENT_SIZE = 72;
const STRING_HEIGHT = 80;

export function ChristmasOrnamentToggle() {
  const isEnabled = useStore(christmasEnabled);
  const shouldReduceMotion = useReducedMotion();
  const [isPulling, setIsPulling] = useState(false);
  const [isHovered, setIsHovered] = useState(false);

  const y = useMotionValue(0);
  // 绳子高度跟随球的位置，确保始终连接
  const stringHeight = useTransform(y, (v) => STRING_HEIGHT + Math.max(0, v));

  const handleDragEnd = () => {
    setIsPulling(false);
    const currentY = y.get();
    if (currentY > DRAG_THRESHOLD / 2) {
      if (isEnabled) {
        disableChristmas();
      } else {
        toggleChristmas();
      }
    }
  };

  return (
    <div className="fixed top-0 right-20 z-90 flex w-[100px] justify-center">
      {/* 绳子 - 高度随拖拽变化 */}
      <motion.div
        className="pointer-events-none absolute top-0 w-[2px] origin-top bg-linear-to-b from-yellow-700 via-yellow-500 to-yellow-400"
        style={{ height: stringHeight }}
      />

      {/* 球体 - 可拖拽 */}
      <motion.button
        className={cn(
          'absolute z-101 cursor-grab touch-none select-none active:cursor-grabbing',
          'rounded-full outline-none focus-visible:ring-4 focus-visible:ring-yellow-400/50',
        )}
        style={{
          width: ORNAMENT_SIZE,
          height: ORNAMENT_SIZE,
          top: STRING_HEIGHT,
          y, // Motion 拖拽自动更新此值
        }}
        drag={shouldReduceMotion ? false : 'y'}
        dragConstraints={{ top: 0, bottom: DRAG_THRESHOLD + 30 }}
        dragElastic={0.2}
        dragSnapToOrigin // 松开后自动回弹
        onDragStart={() => setIsPulling(true)}
        onDragEnd={handleDragEnd}
        onClick={() => toggleChristmas()}
        whileHover={{ scale: 1.05 }}
        whileTap={{ scale: 0.95 }}
        aria-label={isEnabled ? '关闭圣诞模式' : '开启圣诞模式'}
        aria-pressed={isEnabled}
        type="button"
      >
        <OrnamentSvg isEnabled={isEnabled} />

        {/* 拖拽提示 */}
        <AnimatePresence>
          {isEnabled && (isPulling || isHovered) && (
            <motion.div
              initial={{ opacity: 0, y: 10 }}
              animate={{ opacity: 1, y: 30 }}
              exit={{ opacity: 0 }}
              className="pointer-events-none absolute top-1/2 left-1/2 -translate-x-1/2"
            >
              <div className="rounded-full bg-red-950/90 px-3 py-1 text-[10px] text-white">
                下拉关闭
              </div>
            </motion.div>
          )}
        </AnimatePresence>
      </motion.button>
    </div>
  );
}

关键技术点

绳子与球的同步：将 y MotionValue 同时用于球的位置和绳子高度计算，确保两者始终连接
dragSnapToOrigin：Motion 内置的回弹动画，松开后自动回到初始位置
useReducedMotion：尊重用户的动画偏好，禁用拖拽时改为点击切换
dragElastic：设置 0.2 的弹性系数，超出约束时有轻微的弹性效果

性能优化

移动端适配

使用自定义 hook 检测移动端并调整雪花密度：

const isMobile = useIsMobile();
const shouldReduceMotion = useReducedMotion();

// 移动端使用更低的密度
const finalIntensity = isMobile ? mobileIntensity : intensity;
// 移动端禁用鼠标视差
const finalParallaxStrength = isMobile ? 0 : parallaxStrength;

// 尊重用户的动画偏好设置
if (shouldReduceMotion || !isChristmasEnabled) {
  return null;
}

R3F Canvas 配置

<Canvas
  orthographic
  camera={{ zoom: 1, position: [0, 0, 1] }}
  gl={{
    antialias: false,      // 禁用抗锯齿
    alpha: true,
    powerPreference: 'low-power',
  }}
  dpr={[1, 1.5]}           // 限制像素比
/>

文件清单

文件	用途
`src/constants/site-config.ts`	圣诞配置定义
`src/store/christmas.ts`	状态管理
`src/components/christmas/SnowfallCanvas.tsx`	R3F 雪花画布包装器
`src/components/christmas/SnowParticles.tsx`	GLSL 着色器粒子系统
`src/components/christmas/ChristmasLights.astro`	CSS 彩灯装饰
`src/components/christmas/ChristmasHat.astro`	SVG 圣诞帽
`src/components/christmas/ChristmasEffects.astro`	双层雪花包装器
`src/components/christmas/ChristmasOrnamentToggle.tsx`	可拖拽圣诞球开关
`src/styles/christmas/christmas-theme.css`	配色方案

总结

这套圣诞特效模块的设计原则如下：

可插拔：通过配置开关，不影响非节日期间的使用
性能友好：GLSL 着色器 GPU 渲染 + CSS 动画，移动端自动降级
用户可控：提供可拖拽圣诞球开关，尊重 prefers-reduced-motion
跨框架：nanostores 实现 Astro/React 状态同步
层次感：双层渲染 + 鼠标视差，雪花有前后景深度

明年可以在此基础上扩展更多节日特效（新年烟花？万圣节南瓜？），架构已经预留了扩展空间。

Refs

Shadertoy - Just snow - 雪花着色器参考
Toby J 的 CodePen 彩灯参考实现

本文随时修订中，有错漏可直接评论

FE Bits Vol.20 | 博客更新与 FEDAY 见闻，Shadcn Create 发布

Sun, 21 Dec 2025 14:15:00 GMT

本期网址 https://blog.cosine.ren/post/weekly-20 本周刊更新时间期望是在每周天。推荐订阅本周刊的 RSS。公众号前端周周谈 FE Bits，点击阅读原文链接可查看原文。 QQ 讨论小群 598022684，讨论前端技术 & 生活，也可在群里投稿自己的文章，随意加入，比较偏向粉丝群的性质～本周刊文章内容同时也开源在 fe-bits-weekly，欢迎关注。

今天是 2025 年 12 月 21 日，星期天。

这周相当的充实，去参加了 FEDAY 2025，之前没参加过这种活动，很好奇，加上反正今年去了好多活动，感觉这种活动偶尔参加一下还很有意思的，而且顺便也能去长沙旅游一趟，就去了。

参加完的感受是今年的主题特别特别多与 AI 相关的，可以看出 AI 对前端的助益是真的很大，我是比较 AI 乐观主义的，觉得 AI 能帮我省下来很多时间干我想干的事，并且也取代不了前端，但真的需要多进行学习，不断学习。

https://cos.afilmory.art/photos/MVIMG_20251220_090431

cos.afilmory.art

IMG_20251219_183401 on cos’ Photos

余弦的旅行照片与游戏截图~

https://cos.afilmory.art/photos/IMG_20251219_183401

cos.afilmory.art

IMG_20251219_182549 on cos’ Photos

余弦的旅行照片与游戏截图~

https://cos.afilmory.art/photos/IMG_20251219_182549

然后呢，这周将 Fumadocs 里我很喜欢的移动端 header 目录搬到我的博客 astro-koharu 了，我很喜欢～

然后为图片加上了 LQIP，写了在 Astro 博客中实现 LQIP（低质量图片占位符）

然后将性能等，也优化了一下：

优化前	优化后

生态与社区动态

shadcn 发布 3.6：借助新的 npx shadcn create CLI 或者 New Project，现在可以使用 Radix UI 或 Base UI 来创建你自己的定制 shadcn 组件库了。

Storybook 安全公告：又一个 CVE-2025-68429 7.3/10， Storybook v7+ 版本构建时可能会不小心把 .env 打包进去。
Vue start by birkskyum · Pull Request #6055：继 React 和 Solid 之后，TanStack Start 又新增了对 Vue 的支持。
Throttle individual network requests：Chrome DevTools 144 版本可以让你单独对每个网络请求限速进行调试。

小贴士

写了这么一段代码，想要一段可随高度变化可控制间距的虚线。

<svg
  className="pointer-events-none absolute bottom-0 left-px h-[calc(100%+1rem)] w-[1.5px]"
  viewBox="0 0 2 366"
  preserveAspectRatio="none meet"
  aria-hidden="true"
>
  <path d="M0.749978 365.5L0.750106 0" stroke="white" strokeOpacity="0.2" strokeWidth="1.5" strokeDasharray="5.25 5.25" />
</svg>

发现不对！高度特别小的时候挤在一块了。

咋办？使用 vectorEffect="non-scaling-stroke"

developer.mozilla.org

vector-effect - SVG：可缩放矢量图形 | MDN

vector-effect 属性指明绘制对象时要使用的矢量效果。在任何其他合成操作（如滤镜，蒙版和剪辑等）之前，都要应用矢量效果。

https://developer.mozilla.org/zh-CN/docs/Web/SVG/Reference/Attribute/vector-effect

non-scaling-stroke 的使用可以看这篇文章：CSS vector-effect 与 SVG stroke 描边缩放

MDN 的官方解释是：该值修改了笔触的方式。通常，笔触涉及在当前用户坐标系中计算形状路径的笔触轮廓，并用笔触颜料（颜色或渐变）填充轮廓。该值的最终视觉效果是笔触宽度不依赖于元素的变换（包括非均匀缩放和剪切变换）和缩放级别。

为什么不用 border-style: dashed; ？因为他没有办法定义线段的长度和大小，视不同实现而定。

             strokeOpacity="0.2"
             strokeWidth="1.5"
             strokeDasharray="5.25 5.25"
+            vectorEffect="non-scaling-stroke"
           />
         </svg>

完美实现！

使用 `vectorEffect="non-scaling-stroke"` 前	使用 `vectorEffect="non-scaling-stroke"` 后

文章与视频

React Compiler 的静默失败 (以及如何修复它们)：作者分享了在使用 React Compiler 过程中遇到的“静默失败”问题，即编译器在无法优化组件时不会报错，而是回退到标准 React 行为，这可能导致性能下降。为了解决这个问题，作者发现并利用了一个未文档化的 ESLint 规则 react-hooks/todo，通过将其设置为错误级别，可以在编译失败时中断构建过程。
使用 GSAP 构建响应式、滚动触发的曲线路径动画：这篇文章提供了一个好工具 Paths & Control Points，让开发者能够拖拽控制点实时调整曲线。
用 WebGPU 来造一场雪 | Cyandev：手把手教你如何用 WebGPU 在网页上下雪，兼顾性能与效果，让你的博客在圣诞带上节日色彩～
How to type React children correctly in TypeScript：还在为 React 中 children prop 的 TypeScript 类型定义挠头？这篇博文介绍了如何在 React 应用中如何正确使用 TypeScript 定义 children prop 的类型。
Different Page Transitions For Different Circumstances：这篇博文教你如何使用 View Transitions（视图转换）为多页应用程序（MPA）创建差异化的页面切换动画。
How AI Coding Agents Hid a Timebomb in Our App：一篇关于 AI 编程助手“无意间”在应用里埋下了一颗定时炸弹的故事：

一个由 AI 编程助手（AI Coding Agent）删除的代码注释，导致一个关键的 readOnly 属性被移除，进而引发了 React 组件的无限递归渲染。更糟的是，React 19 的 <Activity> 组件将这个 Bug 隐藏了起来，使其在数分钟内都不会崩溃，极大增加了调试难度。作者通过痛苦的调试过程，最终发现罪魁祸首是 AI 删除了注释，以及自己没有为关键的结构性约束编写测试。文章强调了在 AI 辅助开发背景下，测试而非注释，才是确保代码质量和安全的关键。

CSS 新特性

State, Logic, And Native Power: CSS Wrapped 2025：深入解读了 Chrome 团队发布的“CSS Wrapped 2025”年度总结报告，强调 CSS 正从单纯的样式语言向构建动态、强大应用的原生工具集转变，开启了一个激动人心的前端新时代。
Creating Scroll-Based Animations in Full view()：介绍了 CSS animation-timeline 属性中的 view() 函数，它允许开发者创建基于元素在滚动容器（scrollport）中可见性（visibility）的动画。
What Else Could Container Queries… Query?：容器查询（container queries）可不止查询尺寸那么简单，未来还有更多可能性等待探索！
2025 年所有浏览器支持的 11 个 CSS 新特性
Responsive List of Avatars Using Modern CSS (Part 2)：是 “使用现代 CSS 创建响应式头像列表”系列的第二部分，主要探讨如何利用 offset 或 transform 属性，结合 sibling-index() 和 sibling-count() 等 CSS 函数，实现一个响应式圆形头像列表的布局。

工具

Andy Clarke’s Toon Text：Andy Clarke 开发的一款卡通标题文本生成器，它可以生成具有卡通风格的文本，并提供 CSS 代码。介绍文章还重点介绍了其核心功能 Splinter.js，它通过包裹每个字符的标签，并加入 ARIA 属性，在实现逐字样式控制的同时，增强了可访问性，解决了传统工具可能导致辅助技术识别障碍的问题。

Raycast 插件：https://www.raycast.com/j3lte/css-tricks 介绍文章：Search CSS-Tricks Raycast Extension

一个 Raycast 扩展，可以直接从本地计算机搜索 CSS-Tricks 文章。该扩展使用 WordPress REST API 获取实时搜索结果，提供了一种快速查找和复制文章 URL 的方法。单击结果会显示摘要并在浏览器中打开文章。

Codepen 精选

Anderson Mancini(@Andersonmancini): 太阳出来了 ☀️ 我终于完成了将我的“终极镜头光晕”移植到 #threejs WebGPU 的工作。性能简直令人难以置信，因为现在 threejs 已经将遮挡查询直接集成到了渲染管线中。如果你需要知道某个物体是否被遮挡，只需直接向 threejs 查询即可。文档中有示例。这样一来，我就不再需要光线投射器来检测遮挡了，这就是性能大幅提升的原因。如果您想查看结果：https:// planpoint-webgpu.vercel.app

CyberPopover 2025

See the Pen yyNWGNG by jh3y (@jh3y) on CodePen.

在 Jhey Tompkins 这款 Codepen 中，点击闪烁按钮即可打开带有电子音效的 CyberPopover。作为 Jhey 的经典之作，这款 Pen 是可配置的！打开右上角的面板，即可进行设置。

无需 JavaScript 的 Lightbox（灯箱）

See the Pen bNbagPy by daviddarnes (@daviddarnes) on CodePen.

David Darnes 分享了一个快速演示，展示如何使用 Popover API 构建一个简单的照片灯箱，无需 JS，只需不到 30 行 CSS 代码。

Refs

在 Astro 博客中实现 LQIP（低质量图片占位符）

Sat, 20 Dec 2025 09:52:00 GMT

本文由 AI 辅助写作，作记录用

我选择简化一些的实现，不追求 CSS Only 了，因为打算先做博客内部的图片，文章内部的外部图片等后续优化的时候再一起做，放上最终效果在这里：

需要运行一下 nr generate:lqips 就会生成一个 lqips.json 的 json 文件在 assets 下，若没有这个文件则不提供占位符～

以下为 AI 生成的记录，仅做小改。

什么是 LQIP

LQIP（Low Quality Image Placeholder）是一种图片加载优化技术，在高清图片加载完成前，先显示一个低质量的占位符，避免页面出现空白或布局抖动。

常见的 LQIP 实现方式包括：

缩略图方案：生成一张极小的图片（如 20x20），加载时放大并模糊显示
BlurHash：将图片编码为一个短字符串，在客户端解码渲染
主色调方案：提取图片的主色调作为纯色背景
渐变方案：提取多个色彩点生成 CSS 渐变

本文介绍的是渐变方案，通过构建时提取图片的四象限主色，生成 CSS 线性渐变作为占位符。这种方案的优势在于：

零运行时开销：纯 CSS 实现，无需 JavaScript 解码
极小的数据体积：每张图片仅需 18 个字符存储
视觉效果自然：渐变色比纯色更贴近原图的色彩分布

方案设计

整体架构分为三个部分：

flowchart LR
    A[构建时生成脚本<br/>generateLqips.ts] --> B[JSON 数据文件<br/>lqips.json]
    B --> C[运行时工具函数<br/>lqip.ts]

    A -.-> D[sharp 处理图片<br/>提取四象限颜色]
    C -.-> E[Astro 组件调用<br/>生成 CSS 渐变]

数据格式设计

为了最小化 JSON 体积，我们采用紧凑的存储格式：

{
  "cover/1.webp": "87a3c4c2dfefbddae9",
  "cover/2.webp": "6e3b38ae7472af7574"
}

每个值是 18 个十六进制字符，由 3 个颜色组成（去掉 # 前缀）：

字符 0-5：左上角颜色
字符 6-11：右上角颜色
字符 12-17：右下角颜色

运行时将其解码为 CSS 渐变：

linear-gradient(135deg, #87a3c4 0%, #c2dfef 50%, #bddae9 100%)

（PS：这个其实是权衡了牺牲了一点可读性，但是还想保留一点可编辑性，别喷我喵我知道肯定会有人问为什么不用二进制格式）

构建时生成脚本

src/scripts/generateLqips.ts 负责在构建时处理所有图片：

import sharp from 'sharp';
import { glob } from 'glob';
import fs from 'fs/promises';
import path from 'path';
import chalk from 'chalk';

// --------- 配置 ---------
const IMAGE_GLOB = 'public/img/**/*.{webp,jpg,jpeg,png}';
const OUTPUT_FILE = 'src/assets/lqips.json';

// --------- 类型定义 ---------
interface RgbColor {
  r: number;
  g: number;
  b: number;
}

type LqipMap = Record<string, string>;

// --------- 颜色工具函数 ---------

/**
 * RGB 转十六进制字符串
 */
function rgbToHex(rgb: RgbColor): string {
  const toHex = (n: number) =>
    Math.round(Math.max(0, Math.min(255, n)))
      .toString(16)
      .padStart(2, '0');
  return `#${toHex(rgb.r)}${toHex(rgb.g)}${toHex(rgb.b)}`;
}

// --------- 图片处理 ---------

/**
 * 处理单张图片，生成紧凑的颜色字符串
 */
async function processImage(imagePath: string): Promise<string | null> {
  try {

    // Resize to 2x2 to get 4 quadrant colors
    const resized = await sharp(imagePath).resize(2, 2, { fit: 'fill' }).raw().toBuffer({ resolveWithObject: true });

    const channels = resized.info.channels;
    const data = resized.data;

    // Extract 4 colors (top-left, top-right, bottom-left, bottom-right)
    const colors: string[] = [];
    for (let i = 0; i < 4; i++) {
      const offset = i * channels;
      const rgb: RgbColor = {
        r: data[offset],
        g: data[offset + 1],
        b: data[offset + 2],
      };
      colors.push(rgbToHex(rgb));
    }

    // 紧凑存储：3 个颜色（左上、右上、右下），去掉 # 前缀
    // 用于生成 135deg 斜向渐变
    const compact = `${colors[0].slice(1)}${colors[1].slice(1)}${colors[3].slice(1)}`;

    return compact;
  } catch (error) {
    console.error(chalk.red(`  Error processing ${imagePath}:`), error);
    return null;
  }
}

/**
 * 文件路径转短键名
 */
function filePathToKey(filePath: string): string {
  // public/img/cover/1.webp → cover/1.webp
  return filePath.replace(/^public\/img\//, '');
}

// --------- 主函数 ---------
async function main() {
  const startTime = Date.now();

  console.log(chalk.cyan('=== LQIP Generator ===\n'));

  const files = await glob(IMAGE_GLOB);
  if (!files.length) {
    console.log(chalk.yellow('No image files found.'));
    return;
  }
  console.log(chalk.blue(`Found ${files.length} images\n`));

  const lqips: LqipMap = {};
  let processed = 0;

  for (const file of files) {
    process.stdout.write(`\r  Processing ${processed + 1}/${files.length}...`);

    const compact = await processImage(file);
    if (compact !== null) {
      const key = filePathToKey(file);
      lqips[key] = compact;
      processed++;
    }
  }

  const dir = path.dirname(OUTPUT_FILE);
  await fs.mkdir(dir, { recursive: true });
  await fs.writeFile(OUTPUT_FILE, JSON.stringify(lqips, null, 2) + '\n');

  const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
  console.log(chalk.green(`\n\nDone! Generated LQIP for ${processed} images in ${elapsed}s`));
  console.log(chalk.cyan(`Output saved to: ${OUTPUT_FILE}`));
}

main();

核心原理：2x2 缩放

sharp 的 resize(2, 2, { fit: 'fill' }) 将图片缩放到 2x2 像素，每个像素代表原图四分之一区域的平均色：

flowchart LR
    subgraph orig[原图]
        direction TB
        subgraph row1[" "]
            A1["区域 A"]
            B1["区域 B"]
        end
        subgraph row2[" "]
            C1["区域 C"]
            D1["区域 D"]
        end
    end

    orig -.->|2x2 缩放| scaled

    subgraph scaled[2x2 缩放结果]
        direction TB
        subgraph row3[" "]
            A2["A"]
            B2["B"]
        end
        subgraph row4[" "]
            C2["C"]
            D2["D"]
        end
    end

我们选取 A（左上）、B（右上）、D（右下）三个颜色，生成 135 度斜向渐变，这样既能覆盖图片的主要色彩分布，又避免存储冗余数据。

运行时工具函数

src/lib/lqip.ts 提供运行时 API：

// 导入构建时生成的 LQIP 数据
let lqips: Record<string, string> = {};

try {
  const lqipData = await import('@assets/lqips.json');
  lqips = lqipData.default as Record<string, string>;
} catch {
  // 文件不存在时静默失败（首次构建前）
}

/**
 * 图片路径转 LQIP 键名
 */
function imagePathToKey(imagePath: string): string {
  return imagePath.replace(/^\/img\//, '');
}

/**
 * 获取图片的 LQIP 渐变 CSS
 */
export function getLqipGradient(imagePath: string): string | undefined {
  const key = imagePathToKey(imagePath);
  const compact = lqips[key];
  if (compact?.length !== 18) return undefined;

  // 解码紧凑格式：18 字符 → 3 个十六进制颜色
  const c1 = `#${compact.slice(0, 6)}`;
  const c2 = `#${compact.slice(6, 12)}`;
  const c3 = `#${compact.slice(12, 18)}`;

  return `linear-gradient(135deg, ${c1} 0%, ${c2} 50%, ${c3} 100%)`;
}

/**
 * 判断是否为外部图片
 */
export function isExternalImage(imagePath: string): boolean {
  return imagePath.startsWith('http://') || imagePath.startsWith('https://');
}

/**
 * 获取 LQIP 内联样式
 */
export function getLqipStyle(imagePath: string): string | undefined {
  if (isExternalImage(imagePath)) {
    return undefined;
  }
  const gradient = getLqipGradient(imagePath);
  return gradient ? `background-image:${gradient}` : undefined;
}

/**
 * 获取 LQIP props（用于组件）
 */
export function getLqipProps(imagePath: string): { style?: string; class?: string } {
  if (isExternalImage(imagePath)) {
    return { class: 'lqip-fallback' };
  }

  const style = getLqipStyle(imagePath);
  return style ? { style } : {};
}

外部图片降级处理

对于外部图片（用户自定义的封面 URL），我们无法在构建时获取，因此提供 CSS 降级方案：

/* src/styles/components/lqip.css */
.lqip-fallback {
  background-color: hsl(var(--muted));
}

在 Astro 组件中使用

文章卡片封面

PostItemCard.astro 中应用 LQIP：

---
import { getLqipProps } from '@lib/lqip';

const finalCover = cover ?? randomCover ?? defaultCoverList[0];
const lqipProps = getLqipProps(finalCover);
---

<a href={href} style={lqipProps.style} class={cn('relative overflow-hidden', lqipProps.class)}>
  <Image src={finalCover} width={600} height={186} loading="lazy" alt="post cover" class="h-full w-full object-cover" />
</a>

页面横幅

Cover.astro 中应用 LQIP：

---
import { getLqipStyle } from '@lib/lqip';

const bannerLqipStyle = getLqipStyle('/img/site_header_1920.webp');
---

<div class="relative h-full w-full" style={bannerLqipStyle} id="banner-box">
  <Image src="/img/site_header_1920.webp" width={1920} height={1080} alt="cover" class="h-full w-full object-cover" />
</div>

存储优化

在迭代过程中，我们进行了多轮体积优化：

版本	格式示例	每条约
v1 完整 CSS	`linear-gradient(135deg, #87a3c4 0%, ...)`	80 字节
v2 紧凑颜色	`87a3c4c2dfefbddae9`	47 字节
v3 短键名	`cover/1.webp` → 同上	42 字节

最终版本相比 v1 减少约 50% 体积。按 1000 张图片估算：

v1：~80KB
v3：~42KB

对于更激进的优化，还可以考虑：

Base64 编码：3 色 = 9 字节 → 12 字符 Base64
二进制格式：完全避免 JSON 开销

但考虑到可读性和调试便利性，当前的 JSON 格式已经是较好的平衡点。

构建集成

在 package.json 中添加脚本：

{
  "scripts": {
    "generate:lqips": "npx tsx src/scripts/generateLqips.ts"
  }
}

可以在 CI/CD 中配置为构建前置步骤，或在添加新图片后手动执行。

效果展示

以红叶图片为例：

原图路径：/img/cover/2.webp
LQIP 数据：6e3b38ae7472af7574
解码渐变：linear-gradient(135deg, #6e3b38 0%, #ae7472 50%, #af7574 100%)

渐变色准确反映了原图的暖红色调，在图片加载前提供了良好的视觉预期。

总结

本文介绍了一种轻量级的 LQIP 实现方案：

构建时：使用 sharp 提取图片四象限主色，生成紧凑的颜色字符串
运行时：解码为 CSS 渐变，作为图片容器的背景
降级策略：外部图片使用纯色占位符

这种方案的核心优势在于零运行时开销和极小的数据体积，非常适合静态站点生成器如 Astro、Next.js 等场景。

Refs

CSS-only LQIP - 原始灵感来源，使用 20 位整数编码的高级方案
sharp 文档 - Node.js 高性能图片处理库
BlurHash - 另一种 LQIP 方案

本文随时修订中，有错漏可直接评论

FE Bits Vol.19｜站点新功能与 React 披露两个新的 RSC 漏洞

Sun, 14 Dec 2025 12:46:00 GMT

本期网址 https://blog.cosine.ren/post/weekly-19 本周刊更新时间期望是在每周天。推荐订阅本周刊的 RSS。公众号前端周周谈 FE Bits，点击阅读原文链接可查看原文。 QQ 讨论小群 598022684，讨论前端技术 & 生活，也可在群里投稿自己的文章，随意加入，比较偏向粉丝群的性质～本周刊文章内容同时也开源在 fe-bits-weekly，欢迎关注。

今天是 2025 年 12 月 14 日，星期天。

本周给我的博客站点增加了无需后端的相关推荐和 AI 摘要功能。

相关推荐是参考了这篇超赞的实现：

alexop.dev

No Server, No Database: Smarter Related Posts in Astro with `transformers.js` | alexop.dev

How I used Hugging Face embeddings to create smart “Related Posts” for my Astro blog—no backend, no database, just TypeScript.

https://alexop.dev/posts/semantic-related-posts-astro-transformersjs/

用 transformers.js 在本地算“语义相似度”，自动挑出最相关的 5 篇文章。

然后自己又实现了一下，支持排除特定文章（比如周刊），还可以选择是否把“正文”也纳入计算：

只用标题+描述：速度飞快，适合文章多的情况，但不是很准。
加上正文：效果明显更好，就是生成会慢亿些。

# 使用 Snowflake/snowflake-arctic-embed-m-v2.0 计算 168 篇文章（标题+描述）的时间
Done! Generated similarities for 168 posts in 4.1s

# 使用 Snowflake/snowflake-arctic-embed-m-v2.0 计算 168 篇文章（标题+描述+正文）的时间
Done! Generated similarities for 168 posts in 219.3s

这速度差别有亿点大，但是我个人很喜欢带正文的结果，效果显然会更好。

那有没有更折中的方案呢？于是我决定再加一个跑 AI 摘要的功能，使用 xsai sdk，本地 LM Studio 使用 qwen/qwen3-4b-2507 模型跑一遍，跑起来结果又快又好！新增文章通过缓存，只需要跑新增文章的摘要就行，而且效果跟使用正文差不多！

文章详情里还有个可折叠的摘要卡片，点开有打字机小动画（尊重无动画偏好）

都在构建时本地跑完 git 提交，线上零开销。后面会继续调模型和缓存等，优化一下，写的比较匆忙。

欢迎来试试新功能！精力有限还没有写部署文档等，但是有一篇尚未发布的让 AI 写的 astro-koharu-使用指南，可能会有错漏，但是大体配置上差不多，求 star～

github.com

GitHub - cosZone/astro-koharu: astro-koharu 是一个萌系/二次元/粉蓝配色的 astro 主题博客，灵感来自 Hexo 的 Shoka 主题，加了很多自己的小巧思，性能优越。

astro-koharu 是一个萌系/二次元/粉蓝配色的 astro 主题博客，灵感来自 Hexo 的 Shoka 主题，加了很多自己的小巧思，性能优越。 - cosZone/astro-koharu

https://github.com/cosZone/astro-koharu

很开心，忙里偷闲写这些东西，超级开心。

生态与社区动态

React Router’s take on React Server Components：React Router 正在添加 RSC 支持。

你知道 React Router 正在添加对 React Server Components (RSC) 的支持吗？虽然目前还处于实验阶段，但距离正式发布已经非常接近了，而且我认为 React Router 对 RSC 的实现非常出色。

Three.js r182 released ：进行了全面升级，核心改动包括迁移到 ESLint 9、引入 flat config、对 WebGLRenderer 与 WebGPURenderer 进行多项性能与功能优化（如更高效的阴影映射、EAC 纹理支持、VSM 代码重构），节点系统得到显著改进（支持更多类型、优化缓存、引入 float packing/unpacking），同时大量 bug 修复、文档清理与示例更新，整体提升了代码质量、可维护性与渲染效率。

一些官方示例：

Deno 2.6: dx is the new npx：Deno 2.6 通过引入 dx（类似 npx）简化了包二进制的执行，新增细粒度权限控制与权限代理，使用 Go 编写的 tsgo 加速 TypeScript 类型检查，并支持 Wasm 源码导入。安全方面加入 deno audit 与 --socket，改进依赖管理与脚本审批。
微软推出 VS Code Insiders 播客：由 Visual Studio Code 官方团队打造，深度访谈开发者、产品经理以及社区贡献者，解密新特性、实验工具和 AI 驱动的工作流。

想知道世界上最受欢迎的代码编辑器背后究竟发生了什么吗？ VS Code Insiders Podcast 将为你揭开神秘面纱，带你深入了解塑造 Visual Studio Code 未来的功能、决策和人员。
使用 Chrome DevTools MCP，让您的编码代理调试浏览器会话：Chrome DevTools MCP 终于能让你的 AI 编程助手直接介入浏览器调试了，更丝滑了！好耶！

如需将 chrome-devtools-mcp 服务器连接到正在运行的 Chrome 实例，请使用 —autoConnect 命令行实参来设置 MCP 服务器

注意：在 Chrome M144 达到稳定版之前，您必须指定 —channel=canary

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest", "--autoConnect", "--channel=canary"]
    }
  }
}

为您希望看到的网络功能投票：现在，你可以通过点赞 (upvote) 来影响你最想看到的 Web 特性啦！

WebDX 社区组织推出了一项新功能，允许开发者直接通过“点赞 (upvote)”来表达对特定 Web 特性的需求，以帮助浏览器厂商优先考虑开发。虽然点赞多不代表直接采纳，但开发者的需求将成为浏览器厂商决策的重要参考因素。

你是否曾经在 Can I Use 网站上看到某个你非常想使用的功能被标记为红色，然后恨不得直接戳戳浏览器厂商，说：“嘿，我需要这个功能！”？现在你可以了。

WebDX 社区小组推出了一种新方式，让您可以直接表达哪些 Web 功能对您来说最重要。现在，您可以为希望在主流浏览器之间实现互操作的功能投票。

从今天起，您可以在 web.dev、 caniuse.com 和 webstatus.dev 上找到这些已集成的点赞功能。其他平台，例如 MDN，也在研究类似的集成方案。

React 在研究 React2Shell 过程中披露了两个新的 RSC 漏洞

React 在研究 React2Shell 过程中披露了两个新的 RSC 漏洞：CVE‑2025‑55184 与 CVE‑2025‑67779（高危 - 拒绝服务）以及 CVE‑2025‑55183（中危 - 源代码泄露）。这些缺陷可被恶意 HTTP 请求触发，导致服务器无限循环或泄露服务器函数内部代码。React 已在 19.0.3、19.1.4、19.2.3 版本中修复，受影响的框架与打包器（如 Next、React‑Router、Vite 等）亦需同步升级。

react.dev

Denial of Service and Source Code Exposure in React Server Components – React

The library for web and native user interfaces

https://react.dev/blog/2025/12/11/denial-of-service-and-source-code-exposure-in-react-server-components

拒绝服务（高危）： CVE-2025-55184 与 CVE-2025-67779 (CVSS 7.5) 可被恶意 HTTP 请求触发，导致服务器无限循环
源代码暴露（中等）： CVE-2025-55183 (CVSS 5.3) 可能会泄露服务器函数内部代码，源代码中硬编码的 secret 可能会被暴露，运行时 secret 如 process.env.SECRET 不受影响。

官方解释称：

重大漏洞披露后，往往会发现后续漏洞。当一个重大漏洞被披露后，研究人员会仔细检查相邻的代码路径，寻找变种的利用技术，以测试初始缓解措施是否可以被绕过。这种模式在整个行业中普遍存在。例如，在 Log4Shell 之后，随着社区对原始修复程序的审查，又报告了其他 CVE。额外的披露可能会令人沮丧，但这通常是健康应对机制的标志。

只有源代码中的 secret 才能被泄露。源代码中硬编码的 secret 可能会被暴露，但运行时 secret 如 process.env.SECRET 不受影响。暴露代码的范围仅限于服务器函数内部的代码，这可能包括其他功能，具体取决于捆绑器提供的内联支持程度。一定要核对生产包。

nextjs.org

Next.js Security Update: December 11, 2025

Two additional vulnerabilities have been identified in React Server Components. Users should upgrade to patched versions immediately.

https://nextjs.org/blog/security-update-2025-12-11

Next 用户可以使用 npx fix-react2shell-next 进行升级。

我看到这个消息的第一想法嘛，如下：

Shopify Editions Winter 2026

这是每半年固定发布，用于介绍 Shopify 又做了哪些功能更新的网站！

性能和兼容性可能相对一般，但做了完整的移动端适配，纯炫技网页，浓缩了超多细节和彩蛋和 CSS 新特性。

shopify.com

Shopify Editions | Winter ’26

The commerce renaissance is here. Explore 150+ product updates across AI, retail, and more.

https://www.shopify.com/editions/winter2026

彩蛋 1：点击钥匙，会弹出一个新的无边框窗口来进行解锁。应该用到了跨窗口通信

以前有一个类似的尝试用 three.js 实现了这个跨窗口的粒子动画，我猜应该是和这个一个原理，GitHub 仓库

彩蛋 2：解锁后这个窗口还能跟着原来的页面滚动。

彩蛋 3：点击帽子

技术解析：

jhey ʕ•ᴥ•ʔ(@jh3yy)：今年的版本页面真是太棒了——有太多精彩的细节了 ‍ 很荣幸能参与其中，团队表现出色除了令人惊叹的 WebGL 技术之外，还巧妙地运用了 CSS 容器查询、计数器、过渡/动画和 SVG！

文章与视频

我在制作微型 GLSL 演示时学到的一系列技巧和技巧：作者分享了自己在制作 512 字符限制的微型 GLSL（OpenGL Shading Language）图形演示过程中，积累的一系列图形渲染技巧与心得。
TypeScript 7 的进展 - 2025 年 12 月：TypeScript 团队把编译器和语言服务迁移到原生代码（代号 Project Corsa），现在已提供可在 VS Code 中使用的预览版。编辑器功能完整、性能提升显著，编译器在类型检查和增量构建上几乎全兼容 5.9，并实现十倍左右的速度提升。文章还列出了与 5.9 的差异、即将废弃的选项以及后续路线图，强调 6.0 将是基于旧代码的最后一次发布，之后所有重点转向 7.0。

今年早些时候， TypeScript 团队宣布，我们一直在将编译器和语言服务移植到原生代码，以充分利用原生代码的优势，从而获得更佳的原始性能、内存使用效率和并行处理能力。这项工作（代号“Project Corsa”，即将更名为“TypeScript 7.0”）是一项意义重大的工程，但我们在过去的几个月中取得了长足的进步。我们很高兴向大家介绍目前的进展，并展示全新的 TypeScript 工具集如今的“真实”面貌。
Do’s and Don’ts of useEffectEvent in React：了解 React 新增的 useEffectEvent hook，用来在 Effect 中获取最新的 props / state 而不触发 Effect 重新执行。本文列举了它的使用场景、何时可使用与何时不可使用与迁移建议。
Manage a Next.js Monorepo with Prisma：本文展示了使用 Next.js 与 Prisma 在 Postgres 上实现完整的 CRUD Pizza 订餐系统一套流程。（是比较完整的一篇实践，小项目这么折腾全栈是可以的，但是大项目的话，写后端需要慎重～）
2025 回顾：Web 性能有什么新变化？：轻松回顾 2025 年前端性能的变化与新工具，包括 Core Web Vitals 指标的跨浏览器推进、新的 Lighthouse 与 DevTools 检测能力、浏览器 API（如 Scheduler API、软导航观测）的演进、CrUX 和实时监测数据的细化、对图像格式（如 JPEG XL）的最新态势，结尾展望了 2026 年可能的方向（更多 AI 集成与更完整的软导航指标支持）。
Using CSS to fix the irradiation illusion：在深色背景下，白色文本会显得比同等粗细的黑色文本更粗。这种现象叫做“辐照错觉”（irradiation illusion），本文介绍了如何利用可变字体（variable fonts）的 GRAD 轴（grade axis）在不改变字形大小的情况下调整文本的可感知粗细。
Tailwind CSS: Targeting Child Elements (when you have to)：本文详细介绍了如何利用 Tailwind 的任意变体 (Arbitrary Variants) 和 [&_selector] 语法来实现子元素样式控制。

CSS 新特性

CSS Wrapped 2025：一份来自 Chrome 团队的年度 CSS 功能大盘点，看看明年你的 CSS 能玩出什么新花样！

chrome.dev

CSS Wrapped 2025

Sculpt dynamic interfaces, stretch your imagination, and play with these 22 powerful new CSS features that landed in Chrome this year.

https://chrome.dev/css-wrapped-2025/

Fit width text in 1 line of CSS：CSS 新属性 text-grow 用一行 CSS 就能让文本自动填满容器宽度，告别过去的复杂方案，不过它还在实验阶段。
Scrollytelling on Steroids With Scroll-State Queries：使用 CSS 的新滚动状态查询，让网页故事像游戏一样交互。
CSS Scroll-Triggered Animations are coming to Chrome!：Chrome 浏览器将在明年初推出纯 CSS 实现的滚动触发动画。这是一种基于时间，并在特定滚动偏移量（scroll offset）触发的动画，与现有的滚动驱动动画不同。这项功能有望在 Chrome 145 版本正式发布，它将替代部分 IntersectionObserver 的用途。
CSS progress()函数简介：本文介绍了 CSS 新增的 progress() 函数，它能将指定范围内的值映射为 0 到 1 之间的进度值，兼容性一般，还处于 Chrome 的实验阶段。

小贴士

使用 scrollbar-gutter CSS 属性可以为滚动条预留空间，防止滚动条出现或消失时布局发生偏移。

可以将 body （或任何其他容器元素）上的 scrollbar-gutter 属性设置为 stable，以确保始终为滚动条预留空间，防止布局偏移。

scrollbar-gutter 属性是 CSS 中一个相对较新的属性，自 2024 年 12 月起，主流现代浏览器都支持它。因此，可以放心地使用它来渐进式的提升网页的用户体验。

amitmerchant.com

One CSS Trick to Eliminate Scrollbar Layout Shifts

When a webpage’s content exceeds the viewport height, browsers typically introduce a vertical scrollbar. This can lead to layout shifts, especially when navigating between pages or toggling content visibility, as the presence or absence of the scrollbar alters the available width for content.

https://www.amitmerchant.com/one-css-trick-to-eliminate-scrollbar-layout-shifts/

工具

remend：Vercel 推出新 npm 包 remend，自动修复流式 Markdown 的破碎语法，尤其适用于处理 LLM 等应用。提取自 Vercel 的 Streamdown 库，该库是 react-markdown 的即插即用替代方案，专为 AI 驱动的流媒体应用而设计。（PS：与 Streamdown 同类型的 Simon He 的 markstream-vue 也很好！）

React Grab

React Grab：React Scan 的作者 Aiden 出的新工具，它允许你从应用组件中“抓取”上下文，并将其提供给你选择的智能体，以便进行详细的修改。

CLI 设置只需要在你的项目根目录下运行这个命令，将检测您的框架并自动添加必要的脚本。

npx grab@latest init

Claude Code 的设置的话，服务器通过 4567 端口运行，并与 Claude Agent SDK 接口连接。将以下脚本添加到 package.json 中：

{
  "scripts": {
    "dev": "npx @react-grab/claude-code@latest && next dev"
  }
}

Codepen 精选

霓虹正弦波效果 GLSL

Fabio E Zola 的这段 GLSL 动画中，闪烁的正弦波脉动着。您可以暂停动画、截屏，或从顶部的控制面板切换像素比例。

花瓣

See the Pen xbVQQGr by rileyjshaw (@rileyjshaw) on CodePen.

Riley Shaw 分享了一朵梦幻般的 CSS 和 JS 花朵，花瓣如万花筒般旋转

伪 3D 旋转球切换（仅 CSS）

See the Pen xbVydXq by alvaromontoro (@alvaromontoro) on CodePen.

Alvaro Montoro 巧妙地通过移动点阵图案来模拟旋转动画，这个“切换组件是用 HTML 和 CSS 创建的。没有图片，也没有 JS。”

Refs

我的 Claude Code 使用小记 2

Sat, 06 Dec 2025 18:55:03 GMT

本文地址

blog.cosine.ren

我的 Claude Code 使用小记 2 | 笔记 / AI | 余弦の博客

本文地址 https://blog.cosine.ren/post/my-claude-code-record-2 距离我 8 月份写下《我的 Claude Code 使用小记》已经过去了近 4 个月，在这段时间的高强度使用后，是时候分享一些新的体验了。…

https://blog.cosine.ren/post/my-claude-code-record-2

距离我 8 月份写下《我的 Claude Code 使用小记》已经过去了近 4 个月，在这段时间的高强度使用后，是时候分享一些新的体验了。

很短，并且比较支离破碎流水账，主要是为了记录。

使用数据一览

统计工具使用 opcode

数据可以看出，近 30 天我消耗了 743的Token∗∗，使用量集中在单个项目上。背后的原因是：公司报销了几个月的100 的 Token**，使用量集中在单个项目上。背后的原因是：公司报销了几个月的 100的Token∗∗，使用量集中在单个项目上。背后的原因是：公司报销了几个月的100 的 Claude Code Max，让我们几位前端和后端工程师一起尝试从零到一构建一个”相对复杂”的 Swift 原生音视频 APP**。现在 APP 已经接近上架阶段。

使用体验

起初我非常担心账号会被封禁，因为社交媒体上各种封号消息层出不穷。但这 4 个月下来，我的账号一直安然无恙。退一步说，即使真的被封，Anthropic 也会退款，重新注册一个账号即可继续使用。

而要我说我的使用体验的话，那就是：

每月 100 美元的 Claude Code Max 带来的辅助价值，远超这个价格本身。 即使公司后续不再报销，我也会自费继续订阅。

最近 30 天我烧掉的 743$ 的 Token，都是有计划、有目的的使用。给出的结果都很令人满意。

在使用 Claude Code CLI 的同时，我也一直订阅着 Cursor（公司以前报销的年费）和订阅了 3 个月的 Codex。中间有一段时间，体感 Claude Code 确实经历了“降智期”，并且在他们修复了 bug 之后，体验就好起来了，但自从 Claude Opus 4.5 发布后，它就很少让我失望了（当然，对于那些明知它做不来的任务，我也不会强求）。

Codex 我体验的时间则不太多，体感上的话 Codex CLI 的体验还是挺好的，就是太慢了，并且 20$ 特别容易限额，虽说慢工出细活，可是大部分工作还是用 CC 做。

Claude 以前也是，但出了 sonnet 和 opus 4.5 之后做到了有速度的同时，大部分情况不用改，小部分情况下，我只需要小改一下就可以用，那就更没有想用 codex 的理由了。

相比之下，Cursor 最大的作用还是他的 Tab 补全，他的 Agent 我已经很少用了。

我的工作流

Skills

Skills 是 Claude 可动态加载的指令、脚本和资源集合，用于提升特定任务表现。它帮助 Claude 重复执行标准化任务，如文档制作、数据分析或任务自动化。

官方文章：「什么是技能」、「如何在 Claude 中使用」及「如何创建自定义技能」更全面的一篇：Agent Skills - Claude Code Docs

可以通过在 Claude Code 中运行以下命令，将 GitHub 存储库注册为 Claude Code 插件市场：

# 把 https://github.com/anthropics/skills 注册为插件市场
/plugin marketplace add anthropics/skills
# 安装 document-skills
/plugin install document-skills@anthropic-agent-skills

安装插件后，您只需提及该技能即可使用。例如，如果安装了 document-skills 插件，可以让 Claude Code 执行类似这样的操作：“使用 PDF 技能从 path/to/some-file.pdf 中提取表单字段”。

创建自定义技能

只需包含一个 SKILL.md 文件，含 YAML 格式的前置信息与任务指令。前置信息需包含两个字段：name（唯一标识符）和 description（功能与使用说明）。官方有模板示例 template-skill，帮助快速生成自定义技能结构。

也可以使用这个进行新 skill 的创建：claude-code/plugins/plugin-dev

/plugin marketplace add anthropics/claude-code
/plugin install plugin-dev@claude-code-plugins

触发词 “create a skill”, “add a skill to plugin”, “write a new skill”, “improve skill description”, “organize skill content”

这个 plugin-dev 技能可以用来创建 ClaudeCode 的各种东西，不限于配置 Hook、MCP、插件结构、配置、命令、智能体 (Agent) 到技能 (Skill)

用来做什么？

官方提供的几个 Skills 示例在这里，可以按需选择。

algorithmic-art：利用 p5.js 制作算法艺术 (generative art)
brand-guidelines：将 Anthropic 的官方品牌颜色和字体应用于任何需要 Anthropic 风格和感觉的物品。当需要使用品牌颜色或风格指南、视觉格式或公司设计标准时，请使用此功能。
canvas-design：运用设计理念，创作精美的 .png 和 .pdf 格式视觉作品。当用户要求创作海报、艺术作品、设计或其他静态作品时，应该运用这项技能。
doc-coauthoring：引导用户完成结构化的文档协作工作流程。适用于用户需要编写文档、提案、技术规范、决策文档或类似结构化内容的情况。目标是编写一份真正对读者有用的文档。
……

我用到的 Skill 主要是他的前端设计技能，现在可以用 Claude Code 的 Skill 弥补他的前端设计技能，在 Claude Code 里用这两条命令：

/plugin marketplace add anthropics/claude-code
# 安装 frontend-design 技能
/plugin install frontend-design@claude-code-plugins

其他 Claude Code 官方使用的 Skills 可以在 claude-code/plugins 中找到。

更细致的，就先不深入讲了。

学习项目

使用 Claude Code 的 Plan Mode，以博客项目为例子，看一下 Plan Mode 的流程

> 我需要对这个项目进行学习，学习其整体结构与核心实现，输出一系列 md 文档在 docs 文件夹下供我参考。

Plan Mode 会询问你一些问题，提交后再继续进行规划：

确认后，他会接着进行追问补充：

最后会问你是自动接受更改还是手动允许 edit，有 git 进行管理那当然是自动接受。

Claude Code 特别喜欢画这种 ASCII 图，你也可以在 CLAUDE.md 中特别要求他不画这些。

最终生成的示例文档，可以在这里进行查看。注意只是用来做个示例，项目本身是不断变化的，这个文档只是适合初上手来进行学习。

生成的文档质量嘛，虽然有些地方还是会有错漏，并且经常使用各种 ASCII 图，作为新项目了解学习来说我觉得是够的。（当然，不要傻傻呼呼的认为全都是对的，实际看到哪里还需要以代码为准）

新功能从 0 到 1

使用 Claude Code 的 Plan Mode，让模型只输出“变更计划（哪些文件、改动点、预期 diff）”，先不写代码。
ClaudeCode 的 Plan Mode 会生成计划，并询问一些你可能没讲清楚的地方
补充并 Review 计划完毕后让他按计划生成代码，落到本地跑编译与最小样例。
再次要求模型自检：列出潜在失败场景、边界条件和建议测试用例。
做小改动和对接打磨，然后 Commit

# 使用 Claude Sonnet 4.5
> @docs/overview/10-markdown-system.md 开始进行优化，我有以下需求：[Image #1]
  1. 行内代码 `` 语法 的优化
  2. 代码块 ``` 的优化，希望加上复制按钮，模仿 mac 窗口样式，左侧三个圆点+代码语言显示，右侧是全屏预览、复制按钮
  3. 标题的样式优化，标题后的 # 与标题居中对齐，标题前加一个弱化的小 H3 H4 标签标明是几级标题
  4. 列表样式优化（无序和有序）

Bugfix

这些我就懒得放示例了，也是基本上一句话就可以，有的需要更多的人力介入。

喂给他报错日志/最小复现工程。
让模型列出“定位假说清单、验证步骤、最小改动方案”。
实现、自检

重构/迁移

同样 Plan Mode 描述重构需求，让其生成文档计划等
让模型先写 codemod，只在小部分上试跑。
观察 diff，定义切分点和随时可回滚的边界。
分批推进，并进行回归测试。

模型与工具的选型与切换

好用的模型有很多，成本和使用场景也需要考虑，以下是我选模型的基准：

重要的架构设计/大重构：用强模型（质量优先）。
批量生成测试/样例：用便宜模型（成本优先）。
读 log / 写小脚本/摘要：用更快模型（速度优先）。
小模型可以用 Plan Mode 先生产 “变更计划 + 验收用例” 的 PRD，spec 驱动开发，而大模型负责实现。

Happy

最近在尝试 happy，相当好用，可以手机或平板随时随地访问家里或者服务器上的 Claude Code 写代码。

是因为看到了这条 Tweet 才决定使用一下体验的：

slopus.github.io

Happy - Claude Code Mobile Client

Free, open-source mobile app for Claude Code. Control Claude AI from your phone with end-to-end encryption and seamless workflow.

https://happy.engineering/docs/use-cases/hemingway-technique/

欧内斯特·海明威在写作时使用了一个聪明的技巧。他会说到一半就停下来，或者在他知道接下来要说什么的时候停下来。这样第二天再开始写就容易多了。他不需要考虑从哪里开始。这个想法很简单：通过准备好清晰的下一步来保持你的动力。

作为一名开发者，我听说过把未完成的工作留到第二天早上再继续。但这种提高效率的技巧对我来说从来没用。安排一项有意义的任务需要 10 到 20 分钟，这对于即兴发挥来说太长了。尤其是在我已经加班到很晚的时候，我最不想做的就是再花 20 分钟为明天的工作做准备。

现在有了 Claude Code 和 MCP 工具（适用于 JIRA 或 Linear），一切都改变了。我可以躺在床上运行自定义的睡前任务，而不是刷 Reddit 或 Instagram。我已经设置了 ~/.claude/agents/bedtime.md 文件，用来查找简单的任务。这些任务我今晚可以开始，明天就能完成。

我描述一下我想要的功能或者我正在思考的问题。然后我和克劳德一起花大约 5 分钟时间进行规划。我们制定了一个我满意的实施方案。方案经我批准后，克劳德就开始着手实施。我把手机插上充电器，然后睡觉。

我醒来时，Happy 发来一条通知：“4 个文件待审核，新增 237 行代码”。这件小事让我一天有个美好的开始。

注重隐私的话，可以自部署 happy server 远程操控 claude code 以及 codex，官方也都提供教程，可以说是很贴心了。

2025.12.11 补充更新一下，Happy CLI 0.11.2 自带的版本是没有 Opus 4.5 只有 Opus 4.1 是因为版本太旧，可以参考这个 issue https://github.com/slopus/happy-cli/issues/84

cd $(npm root -g)/happy-coder && npm install @anthropic-ai/claude-code@latest --save

更新就可以用上 Opus 4.5 了！后续的版本更新也一样。

FAQ

Q：我该如何知道哪个模型编程性能最好？ A：WebDev Leaderboard | LMArena 可以作为一部分参考，但是更多的还是要靠自己对性能、成本的考虑。

Q：什么时候不要用 AI？
A：技术债务极重、逻辑到处乱飞的大型老项目，想要用 AI 一定不能直接“给我实现 XXX”，可以用它先梳理一遍老项目的坑，并自己加以补充，再进行实现。强烈推荐看下面的文章。

文章推荐

关于 Claude Code 以及 AI 辅助编程，以下这些文章推荐阅读。

从「写代码」到「验代码」：AI 搭档写走 3 年，我踩出来的协作路线图：在推上看到一篇好文章，写给已经在或准备在真实生产项目里用 AI Coding 的后端 / 全栈工程师和技术管理者。它不会教你「按钮在哪里」「哪个 prompt 最神」，而是想在大约 15 分钟里，帮你搞清楚三件事：哪些任务交给 AI 最「划算」；怎么让项目本身变得更「AI 友好」，提高一次命中率；当生成不再是瓶颈时，工程师应该如何设计验证流程，把时间花在真正值钱的地方。
Migrating 6000 React tests using AI Agents and ASTs：好文章，关于使用 AI 进行重构迁移的教科书式文章。
我使用 Claude Code 开发 Rolldown 的体验：在 Rolldown 开发中高强度使用 Claude Code 进行真实开发的思考与经验分享。

几个月前，我自认为对 AI 认知是比较贴切，能写点脚本、做下网页开发，但处理不了 Rolldown 这种复杂度的项目。而现在，过去两周里，它几乎替我写了所有的代码。整个流程没有魔法，只有跟着官方文档《Claude Code: Best practices for agentic coding》的笨拙使用，仅仅是这样，就已经颠覆了我的认知。
周报 #102 - 我是如何使用 AI 的：作者分享了自己在开发、文档和日程管理中如何高频使用 AI 工具的实战经验，
谈谈 AI 编程工具的进化与 Vibe Coding：“氛围编程（Vibe Coding）” 的实际含义是让 AI 全流程写代码，开发者几乎不干预。当前被泛化为所有 AI 辅助编程形式，但作者主张应将它与与 Context Coding 区分
How to Fix Any Bug：少有的讲述「在 vibe coding 中如何调试问题」的文章～当然也适合正常的 bugfix。
How to write a great agents.md: Lessons from over 2,500 repositories：GitHub 分析了超过 2500 个公开仓库中的 agents.md 文件，归纳出优秀 agents.md 的写法（这个很有用）
OpenSpec 使用心得：安利了 OpenSpec 驱动开发
Writing a good CLAUDE.md：一篇教你如何写出既清晰又高效的 CLAUDE.md 的文章。

我觉得这篇谈谈 AI 编程工具的进化与 Vibe Coding里的一段话说得很好：

从这个阶段开始，水平一般的程序员的数量会开始减少直到消亡，这个过程与其说是 AI 抢走了工作饭碗，不如说是被优秀的程序员抢走了工作饭碗，并且这两者的收入在这个阶段的差距也会不断加大。

时代的大潮浩浩荡荡，我并不想把未来想的过于悲观，也不想把事情讲的过于残酷，但在工业机器的轰鸣下，没有人会真的在意那些古法手工制作者的声音。在计算机出现之前，你也难以想象售票员、电话接线员是多么庞大的一个群体。

当然，我并不是说编程水平一般的程序员就找不到出路了，实际上在 AI 的加持下，一个编程水平一般的程序员，如果有不错的商业嗅觉，加上一定的营销能力，创造的商业价值远比在社会分工中当个螺丝钉要大的多。

过去可能需要很多人相互协作才能完成的工作，利用 AI 的杠杆可以大大的缩减工作时间和人员规模，未来的独立开发和小规模的团队协作一定会变得更加主流。

FE Bits Vol.17｜WebGPU 主流浏览器全支持，AntD 6 正式发布

Sun, 30 Nov 2025 12:35:00 GMT

本期网址 https://blog.cosine.ren/post/weekly-17 本周刊更新时间期望是在每周天目前推荐使用 Folo 订阅本周刊的 Quaily RSS。公众号前端周周谈 FE Bits，点击阅读原文链接可查看原文。 QQ 讨论小群 598022684，日常讨论前端技术 & 生活，也可在群里投稿自己的文章，随意加入，比较偏向粉丝群的性质～本周刊文章内容同时也开源在 fe-bits-weekly，欢迎关注。

今天是 2025 年 11 月 30 日，星期天。

给博客优化了一下 UI，代码块和列表、标题的样式都加上了，然后给博客主题换了个名字，正式一些。

现在的主题叫 astro-koharu，博客的正式地址也挪到了 blog.cosine.ren，很开心。

“小春日和” （こはるびより）指的是晚秋到初冬这段时期，持续的一段似春天般温暖的晴天。也就是中文中的“小阳春”。灵感来自 Hexo 的 Shoka 主题，但不再追求一比一复刻，而是保留它的优点，用更轻量的技术栈，做一款属于自己的个人博客主题。

下一步打算自己弄个评论系统，Remark42 感觉没动力用，想参考 Valine 自己弄一个，然后把旧的评论迁移过去。

生态与社区动态

主流浏览器现已支持 WebGPU：WebGPU 现已在主流浏览器全面支持了，但是 Safari 是 iOS 26 才支持，而且 Safari 移动端给的显存嘛……少少的。
Edge 终于支持网站级扩展开关：新增「允许在此网站使用扩展」功能｜可针对任意网站，一键关闭所有扩展：Edge 出了个实用小功能，可以对单个网站一键关掉所有扩展（这下真的是只要你不做就会有浏览器帮你做这个功能了，想给我那个破插件加一直懒得加来着，Chrome 能不能跟进啊）
npm 再次爆发 “Shai Hulud” 供应链攻击，利用 post-install 脚本窃取 token。
TanStack 最近发布了 TanStack Pacer，这是一个框架无关的性能优化工具集，提供防抖、节流、限流、队列管理与批处理等核心原语，适用于任何 JavaScript 框架。它提供了一个专用的 React 适配器（@tanstack/react-pacer），在核心 Pacer 工具之上提供了一组易于使用的 hook，例如 useDebouncedValue、 useThrottledCallback 、 useQueuedState 和 useBatcher。

Ant Design 组件库发布 v6

Ant Design 6.0 来了！

单开一个标题以表尊重～

React 版本提升：最低要求 React 18，推荐使用 React 19。
启用 React Compiler：在构建产物中优化性能，开发者可自行选择是否开启。
纯 CSS Variables 样式架构：不再兼容 IE，样式实现零运行时（zeroRuntime）模式，支持实时多主题切换。
组件语义化结构：所有组件 DOM 结构优化，支持函数式类名配置 (classNames) 与内联样式 (styles)，提升定制能力与可维护性。
移除废弃 API：彻底移除 v4 遗留逻辑，统一 API 命名，同时兼容 v5 的使用方式。

新组件与功能增强

Masonry 瀑布流组件：优化图片展示与卡片排布体验。
Tooltip 支持平移切换：多内容提示实现滑动过渡。
InputNumber spinner 模式：交互式加减按钮布局更直观。
Drawer 支持拖拽：用户可调整抽屉大小。
模糊蒙版背景：所有弹层默认使用模糊效果，可按需关闭。
不再支持 IE，建议替换废弃 API。

One More Thing —— Ant Design X 2.0

面向 AI 场景的组件库同步升级，提供更智能的交互能力。
新版本强化渲染性能与灵活性，是探索 AI 驱动界面的关键工具。
更多详情可参考 Ant Design X 2.0 正式发布了。

Better Auth v1.4

Better Auth 1.4 发布，引入了无数据库的 Stateless Auth、SCIM Provisioning、OAuth 自定义状态、数据库 joins 优化、JWT 密钥轮换、API Key 二级存储、CLI 索引支持、SSO 域名验证等众多特性。此外，还推出了支持 UUID 主键、强化的邮箱变更流程、新的错误页、更好的插件结构和多项安全改善。

文章与视频

从「写代码」到「验代码」：AI 搭档写走 3 年，我踩出来的协作路线图：在推上看到一篇好文章，写给已经在或准备在真实生产项目里用 AI Coding 的后端 / 全栈工程师和技术管理者。它不会教你「按钮在哪里」「哪个 prompt 最神」，而是想在大约 15 分钟里，帮你搞清楚三件事：
- 哪些任务交给 AI 最「划算」；
- 怎么让项目本身变得更「AI 友好」，提高一次命中率；
- 当生成不再是瓶颈时，工程师应该如何设计验证流程，把时间花在真正值钱的地方。
谈谈不自律的良好生活 - 少数派：很温柔的文章，提出「自洽而非自律」，「好好生活」不靠逼迫，而靠理解与自洽。入选年度我最喜欢的文章，值得停下来，慢慢看。
The Performance Inequality Gap, 2026：作者继续延续多年系列，对 2026 年移动与桌面设备的性能、网络条件及网页负载趋势进行分析。核心观点是：移动端尤其低端 Android 设备的硬件与网络改善速度，赶不上网页体积膨胀的速度。
Why use React?：一篇发问式思考文章，探讨为什么开发者选择 React，以及这项选择对前端用户体验意味着什么。作者倡导让框架留在服务器，充分利用浏览器本身的强大功能。
Migrating 6000 React tests using AI Agents and ASTs：一次关于用 AI Agents 和 AST 自动迁移 6000 个 React 测试的实战记录，是一篇好文章。作者公司使用旧版 React Testing Library 编写了 970 个测试文件，总计 6000 个多测试用例。而升级至 v14 后 API 完全异步化，行为变化大，手动迁移代价极高，于是作者决定尝试用 AI 辅助完成大规模迁移。比较感慨的是其中的迁移过程，最后一周时间共执行 50 次迁移，形成 50 个独立 PR，每个 PR 半小时。作者展望未来 AI 将进一步解放开发者，从“重复劳动”转向更有创造力的工作。
以 0.0001 美分的价格干掉 Next.js 服务器：Harmony Intelligence 团队发现了一个未经身份验证的拒绝服务 (DoS) 漏洞，该漏洞仅需一个 HTTP 请求和极少的资源即可导致自托管的 Next.js 服务器崩溃。通过限制请求大小的反向代理可以防止此攻击；仅靠速率限制不足以提供充分的保护。受影响范围：所有带有中间件的自托管 Next.js 服务器（Vercel 托管的不受影响）。受影响版本：≤15.5.4 的旧版本。缓解措施：升级/ 配置诸如 nginx 反向代理限制请求体大小
用代码和 Git 管理 DNS 记录 —— DNSControl 和 GitHub Actions CI/CD 实践
写在 PicGo 即将 8 周年之际：也是一篇很有「情感」的文章啊。

CSS 新特性

巧用 CSS ::details-content 伪元素实现任意展开动画：聊聊 <details> 元素这几年新增加的 ::details-content 伪元素，使得内容展开收起可实现平滑动画。同时讲解了内容锚点（hash）自动展开机制，以及 scroll-margin-block-start 的小技巧。
light-dark() isn’t always the same as prefers-color-scheme：作者发现新的 CSS 函数 light-dark() 并非 prefers-color-scheme 的替代品，它们在实现逻辑上有细微却重要的差异。prefers-color-scheme 更偏向全局系统偏好，而 light-dark() 更适合组件级主题控制。
How to Add and Remove Items From a Native CSS Carousel (……with CSS)：本文介绍如何利用 CSS Overflow Module Level 5 的新特性（如 ::scroll-button() 与 ::scroll-marker）创建一个完全不用 JavaScript 的原生 CSS 轮播组件。通过结合 HTML 的复选框控制展示项、CSS 伪元素控制滚动行为与可视化反馈，作者实现了可动态增删轮播项、支持自动滚动、滚动锚点定位的完整组件，展示了未来 CSS 在交互与状态管理上的潜力。

工具

Color Palette Pro：一款能像音乐合成器一样自由调制色彩的在线调色工具，支持多种色彩空间与样式切换，实时生成色阶、色环、阴影与高光调和效果，非常适合设计师进行系统化配色或视觉一致性探索。
JavaScript Algorithms and Data Structures 一个涵盖经典算法与数据结构的 JavaScript 示例仓库，其中每个算法和数据结构都有其独立的 README 文件，包含相关的解释和进一步阅读的链接。
williamtroup/Heat.js：Heat.js 是一个零依赖、基于 TypeScript 开发的轻量前端可视化库，可生成可定制的热力图、图表和统计数据。开发者可通过配置 DOM 属性（data-heat-js）或使用 API 快速实现自定义热力图等。

Codepen 精选

Concentric Border Radii

See the Pen YPKBrJX by botteu (@botteu) on CodePen.

“快来看看！这个内容器的边框半径取决于外容器的边框半径以及内外容器之间的内边距。” 在这个来自 botteu 的交互式 Pen 中，您可以滑动滑块来尝试不同的半径、内边距和颜色。

Refs

FE Bits Vol.16｜Cloudflare 事故报告出炉，CSSWG 确认 Masonry 布局语法 grid-lanes

Sun, 23 Nov 2025 11:30:00 GMT

本期网址 https://blog.cosine.ren/post/weekly-16 本周刊更新时间期望是在每周天目前推荐使用 Folo 订阅本周刊的 Quaily RSS。公众号前端周周谈 FE Bits，点击阅读原文链接可查看原文。 QQ 讨论小群 598022684，日常讨论前端技术 & 生活，也可在群里投稿自己的文章，随意加入，比较偏向粉丝群的性质～本周刊文章内容同时也开源在 fe-bits-weekly，欢迎关注。

今天是 2025 年 11 月 23 日，星期天。

网站用 astro-pagefind 实现了无需后端的搜索，好用的。

计划在没有后端的情况下把网站功能完善，然后再逐步加上有后端的功能，这样没后端的也好部署，就像以前用 hexo 的体验一样。

生态与社区动态

Highlights from Git 2.52：Git 2.52 带来了新命令、性能优化，此版本首次使用 Rust 代码来实现 Git 的一些内部功能，Git 3.0 将全面要求 Rust。
Cloudflare 于北京时间 2025 年 11 月 18 日晚间发生全球性网络故障，事件影响遍及多个地区和服务，包括 WARP 及 Application Services，最终在连续两个多小时后逐步恢复正常。

故障时间线与恢复进展 20
起部分地区恢复，之后多次“再爆炸”与恢复循环。 21
官方确认在伦敦禁用 WARP 访问，说明问题基本定位。 21
~21
官方多次更新状态，逐步恢复 Access、WARP 与应用服务（Application Services）。 22
时 X（即 Twitter）网页版恢复访问

如果你好奇原因，那么可以查看官方事故报告。

React 2025 年现状调查：React 生态系统年度调查又开始了。提交截止日期为 11 月 25 日，也就是下周二。感兴趣的可以在这里查看 2024 年的调查结果。

这种调查的填写过程中其实能学到不少东西。类似之前的 JS / CSS 的年度调查。

React 团队近年来以稳健的节奏迭代，引入了 Server Components、Compiler 等，还设立了 React Foundation 进行管理。

Announcing Angular v21：Angular 迎来 v21，这是一次面向未来的版本更新，专注于 AI 集成、可访问性及现代开发体验。
Reddit /r/node 讨论 NestJS 的优缺点，引发社区思考框架选型取舍。

文章与视频

如何撰写出色的 agents.md 文件：来自 2500 多个代码库的经验总结：GitHub 分享了从 2500+ 仓库提炼出的经验，教你如何写出真正有用的 agents.md 文件。
谈谈工作中的犯错 | CatCoding 错误不仅是个人问题，也暴露团队在设计、权限、质量控制、代码 Review 等方面的短板。
从 Cloudflare 故障到代码安全 | Cyandev：从一次 Rust 相关的服务中断聊到内存安全与代码复杂度。
如何使用分层模式在 CSS 中创建 3D 图像：使用 CSS 的 transform-style: preserve-3d 让所有层在三维空间可见，利用透视与光影制造立体幻觉，并通过 perspective、translateZ()、filter 等技巧实现动态的 3D 效果。

Keyframes Tokens 跨项目动画标准化：如何通过将动画关键帧 (@keyframes) 设计为可重用的 Keyframes Tokens，来实现动画系统的标准化与可维护化。
我打赌你不知道可以用 Chrome 浏览器开发工具做的六件事 Part 1：带你发现 Chrome DevTools 中那些被忽略却超实用的隐藏技巧，提升调试效率。

本篇是 Part 1，涵盖前三个内容：

用 console.time() 和 console.timeEnd() 精准计时函数执行。
利用 DOM Breakpoints 实时捕捉元素变化，并自动暂停脚本运行。
用 monitor() 在控制台监听任意函数调用。

断点是真的很重要，严肃学习！

CSS 新特性

通过实验学习更多 CSS random() 功能：作者通过多个实验展示了如何用 CSS 的 random() 函数创造动态有趣的视觉效果，如旋转星空、滚动视差(parallax)星空及基于滚动的点阵动效，虽然目前仅 Safari 技术预览版支持该功能，但文章提供了可视化演示和代码片段，展示了 random() 带来的新创意空间和未来样式系统的潜能。
介绍下与 CSS 自定义组件相关的
() 函数：介绍了 CSS
() 伪类函数，这是 Web Components(网页组件) 的新特性，可用来根据组件内部状态修改样式。
在 Chrome 浏览器 144+ 中，锚点定位具有变换感知功能：Chrome 144 将 Anchor Positioning 改为对 transform 变换敏感（transform-aware），更新后 tooltip、浮层等会根据元素的变换后位置进行定位。
Masonry Switch 语法 #1022：CSS 工作组（CSSWG）确定采用新语法 display: grid-lanes 来启用 CSS Grid Level 3 新增的 Masonry 布局。

小贴士

虽然发过那么多次 CSS 新特性的博文推荐，但是在项目中实际用上的没那么多，决定开个新栏目，记录一下平常真在项目里用上了的小 tip！

CSS scroll-state 用来渐进式的增强滚动容器底部的羽化遮罩时还是很好用的～

/* https://github.com/parcel-bundler/lightningcss/issues/887 */
.scroll-feather-mask {
  container-type: scroll-state;
}
@container scroll-state(scrollable: bottom) {
  .scroll-feather-mask::before {
    content: '';
    background: linear-gradient(to bottom, transparent 0%, var(--gradient-bg-start) 70%, var(--gradient-bg-start) 100%);
    position: absolute;
    left: 0;
    right: 0;
    bottom: 0;
    z-index: 10;
    display: block;
    height: 5rem;
  }
}

参考链接

工具

Free Online Image Converter 无需登录、无需上传服务器的在线图片转换工具，完全运行于浏览器端，支持多种主流与新兴图片格式的相互转换，可调整输出格式及质量，立即下载结果，没有水印、不限数量。
Baseline JS Docs：检测 JavaScript 代码是否符合 Web 平台 Baseline 标准的 ESLint 插件，让代码对所有浏览器都更友好。

趣站与 Codepen 精选

Classic 8×8-pixel B&W Mac patterns

网站：https://paulsmith.github.io/classic-mac-patterns/ 介绍文章： Classic 8×8-pixel B&W Mac patterns

由 Paul Smith 制作的 Classic Mac OS System 1 背景图案，这些极小尺寸的复古像素图案可通过 CSS background-repeat 实现无限平铺效果。尽管源自经典的 Mac OS 设计风格，但它们在现代网页中依然有独特的美感和实用价值。

Creepy Button

See the Pen ZYWKvqW by jkantner (@jkantner) on CodePen.

“这个按钮在监视你”。从 Jon Kantner 这款俏皮的按钮下面探出头来，你会发现一双卡通眼睛正在跟踪你的一举一动。

Liquid Glass Clock

See the Pen YPqqqwr by alexandrevacassin (@alexandrevacassin) on CodePen.

顾名思义，一个液态玻璃数字时钟。