TL;DR​

级联选择的核心是：父级变化时，必须重置子级为有效值。使用 Record<string, Option[]> 类型映射数据，在 onValueChange 回调中同步更新子级状态。

在为客户构建 SaaS 认证系统时遇到此问题，记录根因与解法。

TL;DR​

Supabase Auth + FastAPI 集成有三个常见坑：JWKS 路径不是标准路径、ES256 签名需转换为 DER 格式、用户首次登录时本地数据库无记录。本文提供完整解决方案。

在 RAG 知识库项目中调试混合检索评分问题，以下是完整排查过程。

TL;DR​

Milvus 混合检索的加权融合分数 = 0.7 * dense_score + 0.3 * sparse_score，理论最大值约 0.7。如果用 min_similarity=0.7 过滤，结果几乎全被剔除。解决方案：将阈值降到 0.3，或根据融合策略动态调整。

在 RAG 知识库项目中调试查询结果返回格式问题，以下是完整排查过程。

TL;DR​

RAG /query 接口返回的 sources 字段只包含 metadata，没有每条来源的 similarity 分数。解决方案：在组装响应时，将 metadatas 和 distances 合并，计算 similarity = 1 - distance。

TL;DR​

前端代码已推送到 Git，但线上看不到新功能？根因通常是服务器构建产物未更新。通过对比本地和服务器的 dist/ 目录时间戳即可确认，解决方案是在服务器上重新运行 npm run build。

在 RAG 知识库项目中调试混合检索评分问题，以下是完整排查过程。

TL;DR​

Milvus 混合搜索（Dense + Sparse）有四个常见坑：空稀疏向量报错、Collection 未加载、sparse 格式错误、阈值过高。本文给出每个问题的最小修复代码。

在为企业级 SaaS 系统升级 Node.js 版本时遇到此问题，记录根因与解法。

TL;DR​

Node.js v24 对 Web Crypto API 的实现有变化，jose 库要求密钥必须是 KeyObject 或 CryptoKey 类型。用 crypto.createSecretKey() 包装密钥即可解决。

TL;DR​

模块顶层 const URL = process.env.SERVICE_URL 在 dotenv 加载前就执行了，导致值为 undefined。改用 getter 函数 const getUrl = () => process.env.SERVICE_URL 延迟读取。

TL;DR​

在 Docusaurus i18n 网站中，使用 <a href="/docs/xxx"> 绝对路径会在英文版页面跳转到中文版。解决方案：页面内链接用 <Link to="/docs/xxx">，MD 文档内用相对路径 ./xxx。

TL;DR​

在 plugins 数组中添加多个 @docusaurus/plugin-content-blog 实例，每个实例使用不同的 id、path 和 routeBasePath 即可实现多个独立博客。