Published on

2025-第二十三周

Authors

该周报主要为各个地方内容的汇总整理

技术

指令序言与 JavaScript 的暗物质

TypeScript/JavaScript中的指令序言、魔法注释和编译指示是一些特殊的语法，用于影响代码的解释或转译行为。这些语法被TypeScript、V8等引擎或转译器读取，并用于改变输出或行为。

  • 🧙 JSX 编译指示

    • 例如 /** @jsx h */ 告诉转译器将 JSX 语法转换为 h() 函数。
    • 必须是 C 风格注释（/* */），且必须位于文件开头。
    • 其他类似编译指示包括 jsxFragmentFactory、jsxImportSource 等。

  • 📜 指令序言

    • 如 "use strict"; 是 ECMA 标准中的语法，用于启用严格模式。
    • React 中的 "use client" 和 "use server" 也使用类似语法，但功能不同。
    • 其他提案指令包括 "hide source" 和已废弃的 "use asm"。

  • ✨ 魔法注释

    • 如 //# sourceMappingURL=<url> 用于指定源映射。
    • V8 提出的 //# allFunctionsCalledOnLoad 用于提前编译函数。
    • 早期源映射语法使用 //@ 而非 //#。

  • 🌌 非标准化语法

    • 只有指令序言是 ECMAScript 标准的一部分，而编译指示和魔法注释未被标准化。
    • 这些语法是 JavaScript 中的“暗物质”，常被使用但鲜为人知其名称或原理。

CSS 聚光灯效果 - Frontend Masters 博客

Amit Sheen 分享了一种使用 CSS 和少量 JavaScript 实现的鼠标跟随聚光灯效果，通过 CSS 自定义属性和滤镜实现动态交互。

  • 🎨 基本设置

    • 使用 JavaScript 将鼠标坐标传递给 CSS 自定义属性 --clientX 和 --clientY。
    • 通过 radial-gradient 创建透明圆形聚光灯，跟随鼠标移动。

  • 🖱️ 交互优化

    • 添加 pointer-events: none 避免遮挡页面元素。
    • 使用 em 单位实现效果的比例缩放。

  • 🌟 进阶效果

    • 结合 filter: blur() 和 contrast() 实现“粘性”模糊效果。
    • 通过 mix-blend-mode 控制背景混合模式（如 darken 或 lighten）。

  • 🎨 颜色与主题

    • 支持深色/浅色模式切换，使用 light-dark() 函数动态调整颜色。
    • 可自定义聚光灯颜色（如紫色或青色），但需注意混合模式的影响。

  • 📱 移动端适配

    • 通过 @media (hover: hover) 仅在有鼠标的设备上启用效果。
    • 监听 touchstart 事件动态禁用效果，确保触屏用户正常浏览。

  • 🛠️ 扩展创意

    • 叠加多个渐变或网格图案创造复杂动态效果。
    • 利用鼠标坐标控制其他 CSS 属性（如模糊度或大小）。

  • 🔍 无障碍优化

    • 键盘导航时禁用效果（通过 :focus-visible 检测）。
    • 提供区域悬停关闭功能（如 .reveal:hover）。

  • 🚀 完整示例

    • 结合上述技术实现可滚动页面中的动态聚光灯，支持主题切换和移动端回退。

  • 💡 进一步探索

    • 实验不同渐变、滤镜或混合模式。
    • 引入更多 JavaScript 数据（如鼠标速度）增强交互。

JavaScript 流式写入文件

文章介绍了如何通过浏览器扩展 IDBPort 实现 IndexedDB 数据的跨域名迁移，重点探讨了流式写入和读取大型数据文件（如二进制图像）的技术方案，以避免内存占用过高的问题。

  • 🚀 背景与需求：因域名到期需迁移 IndexedDB 数据，开发了浏览器扩展 IDBPort，支持跨域名数据迁移，需处理包含二进制数据的大文件。
  • 💾 流式写入方案：使用 Blob+Response 组合实现流式写入，避免内存爆炸（如数百 MB 至 GB 级数据），关键 API 包括 Blob、Response、TransformStream 和 TextEncoderStream。
  • ⚙️ 写入流程：通过 TransformStream 构建管道，结合 TextEncoderStream 转换数据格式，最终生成 Blob 并触发流式写入，代码示例仅需 10 行。
  • 📥 流式读取挑战：使用 Blob.stream() 读取数据时需处理数据块截断问题，通过自定义 LineBreakStream 确保按行分割，依赖 TextDecoderStream 和 TransformStream。
  • 🔍 代码验证：提供完整代码示例演示流式读取 Blob 文件，确保不规则数据块（如截断文本）仍能正确解析为完整行。
  • 🌐 应用场景：虽属小众需求，但现代浏览器能高效处理超大文件（如数十 GB），适用于在线压缩工具等场景。

每次导航一次往返

网页导航与数据请求的演变：从传统 HTML 到现代组件化方案

  • 🌐 基础导航：传统网页导航只需一次请求获取 HTML，所有数据已嵌入其中（如文章、评论），无需额外 API 调用。
  • 🔄 REST API 时代：客户端崛起后，数据通过多个 REST 端点获取（如文章和评论分开请求），导致效率下降和潜在瀑布式请求问题。
  • 🧩 组件化数据请求：将数据逻辑与 UI 组件耦合（如useEffect或 React Query），虽提升模块化，但加剧了请求分散和性能问题。
  • 🚀 集中式 Loader：通过路由级loader函数（如 React Router）合并数据请求，减少客户端瀑布流，但牺牲了数据与组件的就近性。
  • ⚡ 服务端 Loader：将loader移至服务端（如 Next.js 的getServerSideProps），利用服务端优化（缓存、低延迟）实现单次高效数据返回。
  • 🔗 服务端函数（RPC）：如 TanStack Server Functions，通过隐式 API 简化调用，但未解决请求分散问题，性能仍依赖客户端实现。
  • 📊 GraphQL 方案：通过组件级片段声明数据需求，自动生成聚合查询，兼顾就近性与单次高效请求（如 Apollo）。
  • ⚛️ React 服务端组件（RSC）：服务端组件直接加载数据并向下传递，结合了服务端 Loader 的效率与组件化的模块性，实现单次请求 + 流式渲染。
  • 🔄 权衡与未来：RSC 类似传统 HTML 的高效性，但以 React 组件为抽象层，无需额外 API，平衡了性能与开发体验。

在 JavaScript 项目中处理路由

现代 JavaScript 框架常使用基于文件的路由，但缺乏统一的路由引用系统。以下是关键实践总结：

  • 🚀 避免硬编码路由：通过常量管理路由，减少拼写错误和重构风险。
  • 🔄 动态路由处理：使用函数生成动态路径，适应复杂项目需求（如用户 ID 参数）。
  • 🛠️ TypeScript 增强：用类型约束确保路由配置一致性，如RoutesConfig类型。
  • 📂 路由分组策略：按功能（静态/查看/编辑）或 CRUD 分组，提升可维护性（如RouteGroup）。
  • ⚖️ 灵活选择模式：根据项目复杂度调整方案，但始终确保移除视图层的硬编码。

示例代码结构：

// 常量文件定义路由
export const ROUTES = {
  static: { root: "/" },
  users: { view: (id) => `/users/${id}` }
};

核心原则：建立统一路由系统，提升代码健壮性与可扩展性。

bridging-commonjs-and-esm-in-nodejs

工具

PicSharp

一个简单、高效且灵活的跨平台桌面图像压缩应用程序。

opossum

Opossum 是一个 Node.js 的熔断器库，用于执行异步函数并监控其执行状态。当错误发生时，它会快速失败并支持回退函数。适用于网络请求、磁盘操作等可能失败的操作，并提供丰富的配置选项和事件监听功能。

  • 🐾 功能概述 - Opossum 是一个 Node.js 熔断器，用于处理异步函数的执行和错误管理，支持快速失败和回退机制。

  • 📜 许可证 - 采用 Apache-2.0 许可证。

  • 📖 文档 - 详细文档可在 nodeshift.dev/opossum/ 查看。

  • 🐛 问题追踪 - 问题提交和追踪地址为 GitHub Issues。

  • ⚙️ 引擎要求 - 需要 Node.js 版本 >= 20。

  • 💡 基本用法 - 通过包装可能失败的异步函数（如网络请求），配置超时、错误阈值和重置时间。

  • 🛑 AbortController 支持 - 支持通过 AbortController 中止超时请求。

  • 🔄 自动更新 AbortController - 提供选项自动更新 AbortController，确保其在半开或关闭状态下可重用。

  • 🛠️ 回退函数 - 可设置回退函数，在熔断器打开时执行，并通过事件监听回退操作。

  • 🔄 状态管理 - 支持熔断器状态的初始化和持久化，适用于无服务器环境（如 AWS Lambda）。

  • 📊 统计信息 - 可以获取和导入熔断器的统计信息，如失败次数、超时次数等。

  • 🌐 浏览器支持 - 可在浏览器中使用，保护 AJAX 调用免受网络故障影响。

  • 🔊 事件监听 - 提供丰富的事件（如 success、failure、open、close 等）用于监控熔断器状态和行为。

  • 🔄 Promise 与回调 - 支持 Promise 和回调函数，可通过 util.promisify 转换 Node.js 风格的回调。

  • 📈 错误阈值计算 - 错误阈值基于失败次数与调用次数的比率，可配置滚动计数窗口调整统计周期。

  • 🔗 请求合并 - 支持合并短时间内相同的请求，提高性能并减少资源消耗。

  • 📊 指标导出 - 提供 Prometheus 和 Hystrix 的指标导出模块，方便监控和告警。

  • ⚠️ 故障排查 - 可能遇到 EventEmitter 监听器过多的问题，可通过调整监听器数量或关闭熔断器解决。

sqlite-js

SQLite-JS 是一个强大的扩展，为 SQLite 添加了 JavaScript 功能，支持通过 JavaScript 代码创建自定义函数、聚合、窗口函数和排序规则，实现灵活的数据操作。

  • 🚀 功能概述：SQLite-JS 允许在 SQLite 中使用 JavaScript 定义标量函数、聚合函数、窗口函数和自定义排序规则。
  • 📥 安装方式：支持从预构建二进制文件（Linux/macOS/Windows/Android/iOS）下载或通过 SQL 命令加载扩展。
  • 🔧 标量函数：处理单行数据并返回单个值，适用于数据转换和计算（如计算年龄）。
  • 📊 聚合函数：处理多行数据并返回聚合结果（如计算中位数或标准差）。
  • 🖼️ 窗口函数：支持访问完整数据集而不折叠结果（如移动平均值或百分位排名）。
  • 🔠 排序规则：定义自定义文本排序逻辑（如不区分大小写的自然排序）。
  • 🔄 跨设备同步：结合 sqlite-sync 可自动同步自定义函数到 SQLite Cloud 集群。
  • 💡 JavaScript 执行：直接在 SQL 中执行 JavaScript 代码（如数学计算或日期格式化）。

trunker

Trunker 是一个轻量级的 Express.js 中间件，用于实现功能标志管理。它支持静态和动态标志评估，可基于标志限制路由访问，并集成环境变量和 TypeScript。

  • 🚀 功能简介：轻量级中间件，帮助管理功能标志，支持同步和异步评估。
  • 🛠️ 核心功能：提供简单的 API 定义标志，支持静态/动态评估、路由限制、环境变量集成和 TypeScript。
  • 📥 安装：通过 npm 或 yarn 安装，快速集成到 Express 项目。
  • 🧩 基础用法：通过 createTrunker 创建实例，定义标志并限制路由访问。
  • 🔒 路由限制：使用 restrict 中间件限制路由，支持单标志或多标志组合。
  • 🌍 环境变量：通过 fromEnv 从 TRUNKER_ 前缀的环境变量加载配置。
  • 🔄 动态标志：支持异步逻辑（如检查用户订阅状态）动态启用/禁用功能。
  • 🛑 手动检查：通过 isFlagActive 在路由中手动验证标志状态。
  • ✏️ 自定义错误：可配置错误响应的格式、状态码和提示模板。
  • 📚 API 文档：提供 createTrunker、fromEnv、isFlagActive 等方法，支持 TypeScript 类型扩展。

philschmid/clipper.js: HTML 转 Markdown 转换器与爬虫工具

Clipper.js 是一个 Node.js 命令行工具，用于从网页抓取内容并转换为 Markdown 格式，支持本地开发和爬取功能。

  • 🚀 功能概述：Clipper.js 是一个基于 Node.js 的工具，能够将网页内容转换为 Markdown 或 JSON 格式，适用于内容归档和笔记记录。
  • 📥 安装方式：通过 npm install -g @philschmid/clipper 全局安装，需额外安装 Playwright 以支持爬取功能。
  • 🛠️ 使用方法：
    • 从 URL 抓取内容：clipper clip -u <url>
    • 从文件或目录抓取内容：clipper clip -i <file/directory>
    • 支持输出为 Markdown 或 JSON 格式。
  • ⚠️ 爬取警告：爬取功能可能对目标网站造成负担，需谨慎使用。
  • 📄 PDF 转换：支持通过 Poppler 将 PDF 转换为 HTML，再转换为 Markdown。
  • 🏗️ 本地开发：提供详细的本地测试和构建指令，支持开发环境下的 CLI 测试。
  • 📜 依赖库：使用 Mozilla Readability 解析内容，Turndown 转换 HTML 为 Markdown，Crawlee 进行网站爬取。

toolwind/anchors: Tailwind CSS 锚点定位工具，提供简洁 API 实现灵活声明式定位，支持自定义锚点相对位置。

这是一个关于 Tailwind CSS 插件 "Anchors for Tailwind CSS" 的概述，该插件提供了对 CSS 锚点定位 API 的声明式支持。

  • 🚀 功能概述：插件为 Tailwind CSS 提供了 CSS 锚点定位 API 的支持，包括定义锚点（anchor-name）和相对于锚点定位元素（position-anchor、position-area 等）。
  • 📦 安装方式：通过 npm 安装 @toolwind/anchors 并在 Tailwind 配置文件中引入。
  • 🛠️ 使用方法：
    • 使用 anchor/{name} 定义锚点。
    • 使用 anchored/{name} 将元素附加到锚点。
    • 使用 anchored-{position} 指定元素的定位区域。
  • 🔄 视图过渡集成：每个 anchored/{name} 类包含 view-transition-name，支持使用浏览器原生视图过渡 API 进行动画处理。
  • 📚 额外资源：提供了 MDN 指南、CSS Tricks 文章和规范链接，帮助用户更好地理解和使用 CSS 锚点定位。
  • 🌟 特点：声明式锚点定位、完全支持原生 CSS 属性、易于控制的偏移量、内置视图过渡支持、完全 JIT 兼容无需运行时。

toss/es-git: 专为 Node.js 打造的现代 Git 库，凭借 N-API 驱动，实现极速安装与坚如磐石的稳定性。

es-git 是一个为 Node.js 构建的现代 Git 库，通过 N-API 提供极速安装和稳定性能，支持跨操作系统的高效 Git 操作。

  • 🚀 项目简介：es-git 是一个基于 Node.js 的现代 Git 库，提供简单直观的接口，支持复杂的 Git 操作，内置 TypeScript 类型确保开发效率。
  • ⚡ 高性能：通过 napi-rs 和 git2-rs 编译原生模块，绑定 libgit2，实现跨操作系统的高性能 Git 功能。
  • 📦 便捷安装：提供预构建的原生模块，无需依赖 node-gyp 或本地编译，安装快速无忧。
  • 📚 示例代码：支持克隆仓库等基础操作，例如 cloneRepository 可直接从远程仓库克隆代码。
  • 🌐 多语言支持：文档提供英文和韩文版本，方便不同开发者使用。
  • 🔧 开发友好：内置 TypeScript 类型，集成测试和构建工具（如 Vitest、Rustfmt）。

更新

Babel 8 测试版发布 · Babel

Babel 8 Beta 版本正式发布，标志着经过近两年的开发，所有计划中的破坏性变更已完成，并清理了大量技术债务。团队呼吁用户在实际项目中测试该版本以发现问题。

  • 🎉 Babel 8 Beta 发布：完成所有破坏性变更，大幅减少技术债务
  • 🧪 需实际项目测试：团队自 Alpha 阶段已内部使用，但需更多用户反馈
  • 📚 升级资源完备：提供用户迁移指南、API 开发者指南及临时文档网站
  • ⚡ ESM 专属包：Babel 8 仅支持 ESM，借助 Node.js 20 的 require(esm) 实现
  • 🔍 详细变更记录：GitHub 可查看各 Alpha 版本的完整更新日志
  • 🚧 后续计划：与主流项目协作适配、分离 Babel 7/8 代码分支、修复已知问题
  • 🐞 呼吁参与：鼓励用户测试并提交 GitHub Issue 反馈问题

宣布 Rolldown-Vite | 归零

Rolldown-Vite 是一个基于 Rust 的新一代打包工具，旨在提升 Vite 的性能，现已达到与当前 Vite 版本的功能对等，可作为直接替代方案使用。早期测试显示，生产构建时间减少了 3 倍至 16 倍，内存使用量降低了高达 100 倍。未来，Rolldown 将成为 Vite 的默认打包工具。

  • 🚀 性能提升：Rolldown-Vite 作为 Vite 的替代方案，可显著减少构建时间和内存使用。
  • 🔧 简单替换：通过修改 package.json 中的别名或覆盖依赖，即可轻松切换到 Rolldown-Vite。
  • ⚙️ 兼容性优先：已通过 Vite 生态系统的兼容性测试，但部分高级用例可能存在兼容性问题。
  • 🛠️ 插件支持：插件作者可立即测试其插件，部分插件可能需要调整以兼容或优化性能。
  • 📊 实际效果：早期用户报告构建时间大幅减少，如 GitLab 从 2.5 分钟降至 40 秒，内存使用减少 100 倍。
  • 🔮 未来计划：包括开发全捆绑模式的开发服务器，进一步优化性能，并分三个阶段将 Rolldown 整合到 Vite 中。

AI

Cursor 1.0

Cursor 1.0 版本带来了多项新功能，包括 BugBot 自动代码审查、Background Agent 全面开放、Jupyter Notebook 支持、记忆功能测试版、一键安装 MCP 服务器、更丰富的聊天响应以及新的设置和仪表板界面。

  • 🐛 BugBot 自动代码审查：自动检查 PR 中的潜在问题，并通过 GitHub 评论提供修复建议。
  • ☁️ Background Agent 全面开放：远程编码代理功能现已对所有用户开放，可通过云图标或快捷键启动。
  • 📊 Jupyter Notebook 支持：Agent 可直接在 Jupyter 中创建和编辑多单元格，提升数据科学任务效率（仅支持 Sonnet 模型）。
  • 🧠 记忆功能（测试版）：Cursor 能记住对话内容并在未来引用，支持按项目管理。
  • ⚡ 一键安装 MCP 服务器：简化 MCP 服务器设置，支持 OAuth 认证，提供官方服务器列表。
  • 📊 更丰富的聊天响应：支持在聊天中渲染 Mermaid 图表和 Markdown 表格。
  • ⚙️ 新设置与仪表板：优化界面，新增使用分析、团队统计和网络诊断功能。
  • ⌨️ 快捷键改进：Cmd/Ctrl+E 可快速打开 Background Agent 控制面板。
  • 🔗 功能增强：支持 PDF 解析、并行工具调用加速响应、折叠工具调用等。
  • 👥 团队管理：企业版限制稳定版本访问，管理员可禁用隐私模式并查看 API 用量数据。
  • 🤖 模型更新：Gemini 2.5 Flash 现已支持 Max 模式。

其他

在机器大量生产平庸之作的这个时代，自己动手做点什么吧。让它不完美。让它粗糙。就这么去做。

  • 《这个时代，没人在乎你写了什么》

习惯使用 AI 大模型的下一代人，将不知道图书馆的用途。

  • Benjamin Breen

我们生命中最美好的时刻，并非是那些接受给予、放松享受的时刻，而是那些为了完成一件困难而有价值的事情，自愿将身心发挥到极限的时刻。

  • 米哈里·契克森米哈赖，"心流"（flow）概念的提出者
Discuss on Twitter • View on GitHub