Published on

2025-第二十周

Authors

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

技术

自由地使用 Git worktree 实验你的代码

本文介绍了 Git 工作树（worktree）的概念及其使用方法，重点阐述了如何通过创建多个工作树来同时处理不同任务（如紧急修复和新功能开发），而无需干扰当前工作环境。文章还详细说明了工作树的创建、列表查看、移动、移除等操作，并提供了实用建议以避免管理混乱。

  • 🔄 Git 的设计初衷：Git 支持实验性操作，允许用户尝试新想法，因为工作状态会被安全跟踪并可回退。
  • 🏠 工作区的混乱：在创新过程中，文件可能被重命名、移动或修改，导致工作区变得不稳定。
  • 🌳 Git 工作树的作用：通过创建链接的仓库副本，可同时检出多个分支，独立处理不同任务（如紧急修复）。
  • 🛠️ 创建与使用工作树：示例中通过git worktree add命令创建新工作树，并在其中提交更改，最后合并或推送。
  • 📋 管理工作树：使用git worktree list查看活动工作树，git worktree move移动位置，git worktree remove删除。
  • 🧹 清理建议：完成任务后及时移除工作树，避免仓库副本过多，保持简洁。
  • 🚀 灵活性提升：工作树为 Git 仓库管理提供更高灵活性，避免频繁切换分支或保存临时状态。

指南：JSON-LD | Next.js

Next.js 应用中的 JSON-LD 结构化数据实现指南

  • 📜 JSON-LD 简介

    • 结构化数据格式，帮助搜索引擎和 AI 理解页面内容（如人物、事件、产品等）。

  • 🛠️ 实现方法

    • 在 layout.js 或 page.js 中使用 <script> 标签嵌入 JSON-LD。
    • 示例代码：通过 dangerouslySetInnerHTML 注入动态生成的 JSON-LD 数据。

  • 🔍 验证工具

    • 推荐使用 Google 的 Rich Results Test 或通用 Schema Markup Validator 测试数据有效性。

  • 💡 类型支持（TypeScript）

    • 可通过社区库（如 schema-dts）为 JSON-LD 添加类型提示，提升开发体验。

  • ⚠️ 注意事项

    • 需确保 JSON-LD 数据与页面内容一致，避免误导性标记。

现代滚动阴影：利用滚动驱动动画实现 | CSS-Tricks

现代滚动驱动动画技术通过 CSS 的animation-timeline属性实现滚动阴影效果，无需 JavaScript 即可为水平滚动元素添加边缘渐隐效果。

  • 🌟 通过 CSS 的mask属性和线性渐变实现滚动元素的边缘渐隐效果
  • 🛠️ 使用@property定义自定义属性--left-fade和--right-fade，并指定其语法和初始值
  • 🎨 创建scrollfade关键帧动画，控制左右边缘的渐隐效果
  • 📜 将动画与滚动位置绑定，使用animation-timeline属性实现滚动驱动动画
  • 📱 技术适用于水平滚动表格、轮播图等场景，且不受背景或内容影响
  • ⚠️ 目前部分浏览器（如 Safari）尚未支持animation-timeline，但不影响基本功能
  • 🚀 展示了 CSS 技术的进步，实现了实用且美观的交互效果

高度之谜 - 揭开 CSS 中基于百分比的高度的神秘面纱

本文探讨了 CSS 中高度百分比设置失效的原因及其解决方案，解释了宽度和高度的计算差异，并提供了使用 Flexbox 和 Grid 布局的实用建议。

  • 🧩 CSS 高度百分比失效的原因：当父元素高度依赖于子元素时，设置子元素高度百分比会导致循环计算，浏览器会忽略该声明。
  • 🔄 宽度与高度的计算差异：默认情况下，块级元素的宽度基于父元素计算，而高度基于子元素计算。
  • 📏 固定高度解决百分比问题：为父元素设置明确高度（如height: 300px或height: 24rem）可使子元素的百分比高度生效。
  • 🌐 根元素<html>的特殊性：设置html { height: 100% }会基于视口高度计算，从而支持嵌套百分比高度。
  • ⚠️ min-height的陷阱：使用min-height无法解决百分比高度问题，因为父元素高度仍依赖于子元素。
  • 🎯 Flexbox 与 Grid 布局的解决方案：通过display: grid或flex: 1强制子元素填充父空间，避免高度计算冲突。

理解 StructuredClone：JavaScript 中的现代深拷贝方法 | ClarityDev 博客

JavaScript 中深度复制的现代方法：structuredClone() 的全面解析

  • 🚀 structuredClone()是 JavaScript 中深度复制对象的现代解决方案，解决了传统方法的诸多痛点
  • 🔄 传统深度复制方法包括 JSON.parse/stringify（丢失函数/日期等）、递归克隆（不处理循环引用）和 Lodash 库（需外部依赖）
  • 🎯 structuredClone()优势：原生支持、处理复杂数据结构（循环引用/Map/Set 等）、性能更优
  • ⚠️ 局限性：无法克隆函数、DOM 节点、类实例的原型链、错误对象的堆栈信息和属性描述符
  • 🛠️ 适用场景：嵌套应用状态管理、含循环引用的数据、API 响应快照、实现撤销/重做功能
  • 🌐 兼容性：主流浏览器（Chrome 98+/Firefox 94+）和 Node.js（17.0.0+）均支持
  • 💡 实践建议：数据与行为分离、错误处理、性能权衡、类实例自定义克隆方法
  • 📅 对比传统方法：比 JSON 方式更可靠，比递归克隆更简单，比 Lodash 更轻量（无需依赖）

React 内部机制：哪个 useEffect 会先运行？ – Frontend Masters 博客

概述了 React 中useEffect的执行顺序及其内部机制，通过示例和 React Fiber 架构的解释说明了子组件的 effect 为何先于父组件执行。

  • 🧠 React 的useEffect执行顺序：子组件的 effect 先于父组件执行，这与渲染顺序相反。
  • 🔄 React 生命周期分为三个阶段：触发（Trigger）、渲染（Render）、提交（Commit）。
  • 🌳 React 内部使用 Fiber 树结构来管理组件和更新，每个节点包含子节点、兄弟节点和父节点信息。
  • 🚶♂️ Fiber 树的遍历采用深度优先算法，每个节点会被访问两次，分别用于渲染和提交。
  • ⚙️ 提交阶段（Commit Phase）负责实际的 DOM 操作和 effect 的执行，effect 的执行顺序由遍历顺序决定。
  • 📚 理解这些机制有助于避免复杂组件结构中的潜在问题。
  • ❓ 文章解答了读者关于渲染和 effect 执行顺序的疑问，并提供了代码示例验证。

复杂 React/Next.js 应用的健壮数据获取架构

本文介绍了在 React 和 Next.js 应用中采用"三层数据架构"模式来避免常见问题、技术债务并提升性能的方法。以下是关键要点：

  • 🚀 初始数据获取问题：许多项目开始时简单使用useEffect和fetch，但随着复杂度增加，会出现重复请求、状态管理混乱等问题。
  • 🔍 常见问题列举：包括重复网络请求、过度重新渲染、缓存失效、竞态条件、内存泄漏等 11 个常见问题。
  • 🏗️ 三层架构解决方案：将数据获取分为服务器组件（初始数据）、React Query（客户端缓存）和乐观更新（即时 UI 反馈）三层。
  • 💡 架构优势：分离关注点，使应用更易维护、测试和扩展，尤其适合复杂应用。
  • 📂 目录结构示例：展示了如何组织三层架构的代码，包括 API 路由、React Query 钩子和上下文提供者。
  • 🔄 数据流动：从服务器组件获取初始数据，React Query 管理客户端状态，乐观更新处理用户操作。
  • ⚡ 乐观更新：通过useMutation实现即时 UI 反馈，处理创建和删除等操作。
  • 🧩 上下文整合：使用上下文提供者集中管理数据，避免属性钻取，保持组件简洁。
  • ⚠️ 注意事项：三层架构对简单应用可能过于复杂，但适合大型应用，且可应用于其他框架如 Vue.js 和 Svelte。

工具

GitHub - TanStack/db：用于构建同步超快应用的反应式客户端存储

TanStack DB 是一个反应式客户端存储库，用于构建快速同步的应用程序，扩展了 TanStack Query 的功能，提供集合、实时查询和乐观更新等功能。

  • 🚀 快速查询引擎：支持亚毫秒级实时查询，适用于复杂查询和聚合操作。
  • 🎯 细粒度反应性：最小化组件重新渲染，提升性能。
  • 💪 强大的事务支持：支持乐观更新，带有同步和生命周期管理功能。
  • 🌟 数据规范化：简化后端数据处理。
  • 🔥 后端无关：支持 REST API、GraphQL、轮询等多种后端数据源。
  • 📚 文档丰富：提供使用指南、示例和核心概念说明。
  • 🧱 核心概念：包括集合（Collections）、实时查询（Live Queries）和事务性更新（Transactional Mutators）。

GitHub - NickvanDyke/eslint-plugin-react-you-might-not-need-an-effect: ESLint 插件，用于检测不必要的 React useEffect 钩子，使代码更易理解、运行更快且减少错误。

这是一个 ESLint 插件，用于检测 React 中可能不必要的 useEffect 钩子，旨在提升代码可读性、运行效率并减少错误。

  • 🚀 安装要求：需 ESLint >= v7.0.0 和 Node >= 14，支持 npm 或 yarn 安装。
  • 🔧 配置方式：支持传统配置（.eslintrc）和扁平化配置（eslint.config.js），需添加插件及规则。
  • 🔎 规则功能：检测无效 useEffect 场景（如仅使用内部状态、派生状态等），并推荐更优模式，但会忽略涉及外部状态等复杂情况。

GitHub - isaacs/node-glob: 为 node.js 提供的 glob 功能

node-glob 是一个用于 Node.js 的 glob 功能实现库，支持文件匹配模式，类似于 shell 中的模式匹配。

  • 🌟 功能概述：node-glob 提供了异步和同步的文件匹配功能，支持多种 glob 模式。
  • 📦 安装方式：通过 npm 安装 glob 包，而非已废弃的 node-glob。
  • 🔍 基本用法：支持 glob、globSync、globStream 等方法，可以匹配文件路径。
  • ⚙️ 选项配置：提供丰富的选项，如 ignore、cwd、nodir 等，用于定制匹配行为。
  • 🚀 高级功能：支持 Glob 类，允许复用设置和缓存，提高多次匹配的效率。
  • 📂 路径处理：支持返回 Path 对象，提供更多文件系统信息。
  • ⚠️ 注意事项：在 Windows 上应使用 / 作为路径分隔符，除非设置 windowsPathsNoEscape。
  • 🏆 性能比较：与 fast-glob 和 globby 相比，node-glob 更注重与 Bash 行为的一致性。

GitHub - harrisiirak/cron-parser: 用于解析 crontab 指令的 Node.js 库

一个用于解析和操作 cron 表达式的 JavaScript 库，支持时区、夏令时处理和迭代功能。

  • ⏰ Node.js 库，用于解析 crontab 指令
  • 🛠️ 支持时区和夏令时处理
  • 🔄 提供迭代器功能
  • 📅 支持多种 cron 表达式格式和特殊字符
  • ⚙️ 提供严格模式验证
  • 🌍 使用 Luxon 处理时区
  • 🎲 支持随机值（H 字符）
  • 📂 支持 crontab 文件操作

stagewise

Stagewise 是一个浏览器工具栏，可将前端 UI 与代码编辑器中的 AI 代理连接起来，提供实时浏览器驱动的上下文，支持多种框架，并具有开源和快速安装的特点。

  • 👁️ 项目概述：Stagewise 是一个浏览器工具栏，连接前端 UI 和代码编辑器中的 AI 代理。
  • 🛠️ 功能特点：支持实时选择 DOM 元素、发送上下文给 AI 代理、不影响打包大小，并提供多种框架支持。
  • ⚡ 快速开始：安装 VS Code 扩展并注入工具栏，支持 React、Next.js、Vue、Nuxt.js 和 SvelteKit。
  • 🤖 AI 代理支持：兼容 Cursor 和 Windsurf，GitHub Copilot 支持正在开发中。
  • 📜 许可证：采用 AGPLv3 开源许可证，部分企业功能为商业许可。
  • 🛣️ 路线图：提供项目路线图，展示即将推出的功能和修复。
  • 🤝 贡献：欢迎社区贡献，提供贡献指南和问题反馈渠道。
  • 💬 社区支持：提供 Discord 社区和 GitHub 问题支持，商业使用可联系 sales@stagewise.io。

更新

JavaScript 的新超能力：显式资源管理 · V8

JavaScript 新增显式资源管理功能，通过确定性方式管理资源生命周期，提升代码健壮性和可维护性。

  • 🚀 新增 using 和 await using 声明，自动在作用域退出时调用资源的 [Symbol.dispose]() 或 [Symbol.asyncDispose]() 方法
  • 🔧 引入 [Symbol.dispose] 和 [Symbol.asyncDispose] 符号用于资源清理操作
  • 📚 新增全局对象 DisposableStack 和 AsyncDisposableStack，支持聚合多个可释放资源并按添加顺序反向释放
  • 🚨 新增 SuppressedError 错误类型，解决资源释放过程中错误被掩盖的问题
  • 🔄 示例展示如何用 using 自动释放 ReadableStreamDefaultReader 的锁，避免手动 try...finally 的繁琐
  • 🧩 DisposableStack 提供 use()、adopt()、defer() 和 move() 方法，灵活管理资源生命周期
  • 🌐 兼容性：Chrome 134+ 和 Firefox 134+ 已支持，Safari 和 Node.js 暂不支持，Babel 提供转译支持

RFC：统一的命令式查询方法 · TanStack/query · 讨论 #9135 · GitHub

overview summary
TanStack Query 提出了一个 RFC（请求评论），旨在统一其命令式查询方法。当前存在多个功能相似但用途不同的 API（如 fetchQuery、prefetchQuery 和 ensureQueryData），导致开发者困惑。提案建议合并为单一的 queryClient.query(options) 方法，并通过选项控制行为（如错误处理、缓存策略）。同时引入 staleTime: 'static' 标记静态查询，避免无效缓存更新。

  • 🚀 背景与问题

    • 历史原因导致多个功能重叠的 API（如 fetchQuery、prefetchQuery），命名和行为不一致，开发者难以选择。
    • 示例：prefetchQuery 在每次数据过期时都会重新请求，与“预取”字面含义不符。

  • 🔍 当前 API 的问题

    • 命名混淆：fetchQuery 可能不实际发起请求，prefetchQuery 会重复执行。
    • 使用场景模糊：路由加载器推荐 ensureQueryData，SSR 推荐 prefetchQuery，但功能差异不明显。

  • 💡 提案解决方案

    • 统一为 queryClient.query(options) 和 queryClient.infiniteQuery(options)。
    • 通过选项控制行为（如 throwOnError: false 替代 prefetchQuery 的静默错误）。
    • 新增 staleTime: 'static' 标记完全静态的查询（即使手动失效也不更新）。

  • ⚠️ 注意事项

    • SSR 中需避免直接使用返回数据，推荐 void queryClient.query() 或流式传输。
    • 移除 revalidateIfStale 功能，改为显式组合调用。

  • 📅 ** rollout 计划**

    • v5 版本中逐步弃用旧 API，新版本中移除。

  • ❓ 社区反馈

    • 支持简化 API，但对错误处理方式（throwOnError vs .catch(noop)）存在讨论。
    • 其他建议：统一 Suspense 和无限查询的 Hook 选项（如 useQuery({ suspense: true })）。

  • 🔄 相关讨论

    • 突变（mutation）与查询的差异仍将保留，因其语义不同（副作用 vs 幂等操作）。
    • 未来可能优化 Suspense 集成（如通过 React 的 use() Hook）。

NLWeb

NLWeb 是一个旨在简化网站自然语言交互接口开发的开源项目，通过结合开放协议、Schema.org 语义标准和示例代码，为网站提供便捷的对话式交互能力，同时支持人类用户和 AI 代理的访问。

  • 🌐 目标与愿景

    • 构建 AI 时代的网络基础层，类似 HTML 对文档共享的革命性影响。
    • 通过共享协议和社区协作，实现 AI 增强的普适化网络交互。

  • 🛠️ 技术组成

    • 包含简单协议（基于 JSON 和 Schema.org）与现成实现代码，支持快速部署。
    • 原生集成 MCP 协议（Model Context Protocol），支持自然语言问答。

  • 🔄 工作原理

    • 协议层：定义自然语言交互接口及结构化响应格式。
    • 实现层：利用现有标记（如商品、评论列表）生成对话式界面。

  • ⚙️ 兼容性与扩展

    • 平台无关：支持 Windows、MacOS、Linux 等操作系统。
    • 技术栈灵活：适配多种向量数据库（Qdrant、Milvus 等）和 LLM（OpenAI、Gemini 等）。

  • 📦 仓库内容

    • 核心服务代码、主流 LLM/向量数据库连接器、数据导入工具及简易 Web 前端。
    • 鼓励生产环境自定义集成，避免数据冗余导致的实时性问题。

  • 📄 文档与部署

    • 提供快速入门指南（本地/Azure/GCP 部署）及 API/REST 接口文档。
    • 暂未启用 CI/CD，采用 MIT 开源许可。

  • 🤝 社区与支持

    • 欢迎社区贡献，需遵循贡献指南和商标使用规范（如 Microsoft 品牌要求）。
    • 问题咨询请联系 NLWeb 支持团队。

关键特点

  • 🚀 轻量且可扩展：从云端集群到本地设备均可运行。
  • 🔗 语义网集成：利用 Schema.org 实现数据互通。
  • 🌱 开放生态：提供基础示例，鼓励社区创新超越现有实现。

其他

政企产品经理 AI 工作流分享：需求->产品的敏捷实现（深度长文）

Ben 分享的基于 AI 的「需求直达产品」敏捷工作流，适用于政企行业解决方案架构师、售前、产品经理等角色，旨在通过 AI 工具快速将用户需求转化为可体验的产品原型，解决定制化项目中需求模糊、反复修改的痛点

  • 🎯 适用人群：售前、解决方案架构师、产品经理等需快速转化需求的角色
  • 🏛️ 背景痛点：政府定制化项目中需求不明确→反复修改→开发延期→项目烂尾
  • 💡 核心思路：通过 AI 工具快速生成 MVP 原型，提前收集用户反馈，避免后期大改
  • 🔄 工作流四阶段：
    • 需求阶段 📝：通义转录会议+Google/秘塔搜索补充信息→归档钉钉/飞书文档
    • 设计阶段 🎨：
      • ChatGPT/DeepSeek生成方案→Lovable/v0.dev等工具快速生成原型
      • 多工具并行生成，仅构建前端原型（模拟数据增强真实感）
    • 工程化实现 💻：
      • 下载原型代码→用 Cursor/Windsurf 等 AI 增强 IDE 修改
      • 关键技巧：学习 AI 修改的参数（如 CSS 属性）提升指令精准度
    • 交付部署 🚀：
      • 公网部署：GitHub+Netlify/Vercel 一键上线
      • 本地演示：ngrok 生成临时外网链接
      • PRD 生成：Cursor 分析代码自动输出需求文档
  • 🌟 优势总结：
    • 从需求到 MVP 周期大幅缩短
    • AI 辅助降低技术门槛（非程序员可操作）
    • 版本控制（GitHub）+ 自动化部署提升效率
  • ✨ 关键建议：清晰指令 + 小步迭代 + 保持耐心，实践中学习技术概念
  • 📜 结语：引用陆游诗句强调实践重要性，欢迎交流优化（附联系方式）

除非你参与过历史遗留项目，否则你不能自称高级工程师。

-- infobip.com

Discuss on Twitter • View on GitHub