VTJ.PRO没有内置TailwindCSS，可以通过增加依赖的方式支持 TailwindCSS。
打开设计器的依赖管理面板，点击 + 添加 TailwindCSS 依赖。
填写以下信息：
登录
https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4?.js
在设计器页面管理面板，新建一个页面，打开AI助手，输入提示词：
在当前页面使用 tailwindcss 做一个演示 tailwindcss 用法的页面
页面生成效果
经过验证，TailwindCSS 已经成功接入到VTJ.PRO
在 AI 代码生成工具层出不穷的今天，程序员面临着一个核心问题：如何更高效、更精准地让 AI 理解我们的需求？ 传统的 AI 对话模式需要我们反复描述项目背景、手动关联各种文档和技能规范。这种模式不仅效率低下，还容易因为信息不完整导致 AI 产生“幻觉”，生成结果与预期相差甚远。
鳌虾（Aoxia-code） 正是为解决这些痛点而生。
在 1.0 版本中，鳌虾作为一个 npm 全局工具，首创了“可视化拖拽生成 AI 指令”的工作流，广受好评（详见1.0版本介绍）。 今天，我们正式推出 鳌虾 Aoxia-code 2.0！这一次，鳌虾完成了架构级的蜕变：从独立的 npm 工具，全面进化为沉浸式的 VS Code 插件，并重磅推出了基于流程图的复杂逻辑编排功能，让单页面真正串联成完整的业务流！
传统代码生成器通常依赖“硬编码模板（EJS/FreeMarker）”，一旦业务逻辑发生变化，模板就变得极难维护。 而 鳌虾 走的是另一条路： 元数据编排 + 技能规范约束 + AI 生成 。
在鳌虾 2.0 中，你不再需要手敲冗长的 Prompt。你只需在 VS Code 内部通过拖拽组件搭建页面骨架，再通过连线配置页面间的跳转逻辑。鳌虾会自动将这些视觉化的设计意图，结合项目中的技能规范文件，编译成一段高度结构化的 AI 指令。把这段指令发给 Trae/Cursor，完美契合你期望的源码瞬间生成！
鳌虾 2.0 告别了过去 npm install -g 启动本地服务的繁琐流程。
现在，你只需在 VS Code 插件市场搜索并安装 Aoxia-code Extension tool。按下 Ctrl+Alt+X （Mac 为 Cmd+Option+X）即可在编辑器内部瞬间唤出可视化工作台。它能原生读取你当前工作区的目录结构和规范文件，体验如丝般顺滑。
在前端开发中，对项目目录的把控至关重要。鳌虾 2.0 彻底重构了左侧栏目录树：
src/views），留空则默认加载整个项目。node_modules、.git、.husky 等无关产物），保证树形结构清爽无比，甚至能精确显示目录下的 .vue、.ts 等业务代码文件。在 1.0 版本中，我们解决了“如何快速生成单个页面”的问题。但真实的业务往往是多页面联动的。 鳌虾 2.0 引入了基于流程图的可视化拓扑连线引擎，分为两个维度：
(这里非常适合放一张截图：FlowDesigner 的流程拓扑连线界面，展示模块之间或页面之间带有箭头和路由说明的连线)
前端开发的第一步往往是看接口文档写字段。鳌虾内置了强大的解析引擎，支持四种零成本导入方式：
CREATE TABLE 语句贴进来！鳌虾会自动提取字段名、注释作为 Label，甚至能根据字段类型自动推导前端组件（比如 datetime 变日期选择器， varchar 变输入框，注释里带“状态”自动推导为下拉框）。@ApiModelProperty 等注解，秒变前端结构字典。解析完字段后，进入可视化拼装环节：
如何让 AI 生成的代码符合团队规范？
鳌虾 2.0 继承并强化了 1.0 的规范读取能力。它会自动扫描并读取当前 VS Code 工作区下的技能文件，优先级为：
.trae/skills > .trae/rules > .cursor/rules > .windsurf/rules > .aocode/rules > docs/rules
<rules> 提取：只要在技能文件中标注了 <rules>...</rules> 或 [CODE_RULES_START]...[CODE_RULES_END] 标签，鳌虾 2.0 会通过强大的正则匹配（支持多块扫描），完整提取并编号所有规则片段，精准输送给大模型。| 对比维度 | 传统 AI 编程 | 鳌虾 AoCode 2.0 |
|---|---|---|
| Prompt 输入 | 每次都要手敲完整描述 | 可视化配置，一键生成结构化指令 |
| 技能规范传递 | 手动复制粘贴或反复提及 | 自动读取并按需注入 |
| 多页面交互 | AI 难以理解页面间的跳转与状态共享 | 流程图编排，清晰定义弹窗/抽屉/路由逻辑 |
| 信息完整性 | 容易遗漏关键约束条件 | 结构化输出，确保信息无遗漏 |
| 学习成本 | 需要学习复杂的 Prompt 编写技巧 | 零门槛，所见即所得 |
(这里可以作为总结，放一张最终生成 AI 指令后，代码在 VS Code 中自动写入过程的录屏动图)
Ctrl+Shift+P 执行 Aoxia: Open Aoxia。.trae/skills/table-spec.md 规范。鳌虾 2.0 插件现已正式上架 VS Code 官方插件市场！
打开 VS Code 扩展面板，搜索 Aoxia-code Extension tool 即可安装体验！（开发者：Zhang-Lab）
⚠️ 特别提示（针对 Trae 用户）： 由于 Trae 默认使用的是其内部审核的插件市场，如果在 Trae 的插件面板中搜索不到
Aoxia-code Extension tool，直接用浏览器访问：marketplace.visualstudio.com/_apis/publi… 它会把.vsix文件下载下来。只需要打开trae,从VSIX安装。
我们不是要用低代码取代程序员，而是用**“可视化编排 + 流程定义 + AI”**把程序员从最无聊的增删改查和写 Prompt 的泥潭中解放出来，去思考更有价值的系统架构。
欢迎大家下载体验！如果有任何建议或发现了 Bug，欢迎在评论区留言交流！如果觉得好用，别忘了在插件市场留下一个五星好评哦~ ⭐️⭐️⭐️⭐️⭐️
上节我们学习了布局和页面的使用，本节来聊聊链接和导航。在 Web 应用中，页面之间的跳转是最基本也是最重要的功能之一。Next.js 提供了强大的导航系统，不仅使用简单，而且性能优化做得非常好。
Link 组件是 Next.js 中进行导航的主要方式，它扩展了 HTML 的 <a> 标签，提供客户端导航功能。很多初学者会问，为什么不直接用 <a> 标签呢？其实 <Link> 组件在底层做了很多优化，比如预加载、客户端导航等，能让页面切换更加流畅。
使用 Link 组件非常简单，只需要导入并使用它：
import Link from 'next/link'
export default function Navigation() {
return (
<nav>
<Link href="/">首页</Link>
<Link href="/about">关于</Link>
<Link href="/contact">联系</Link>
</nav>
)
}
在实际开发中，我们经常需要根据数据动态生成链接，比如文章列表、产品列表等：
import Link from 'next/link'
export default function PostList({ posts }: { posts: Post[] }) {
return (
<ul>
{posts.map((post) => (
<li key={post.id}>
<Link href={`/posts/${post.slug}`}>{post.title}</Link>
</li>
))}
</ul>
)
}
Link 组件支持很多有用的属性，可以满足各种导航需求：
import Link from 'next/link'
export default function Links() {
return (
<>
{/* 新标签页打开 */}
<Link href="/about" target="_blank" rel="noopener noreferrer">
关于（新窗口）
</Link>
{/* 替换当前历史记录 */}
<Link href="/dashboard" replace>
仪表盘
</Link>
{/* 滚动到特定位置 */}
<Link href="/about#team" scroll={false}>
关于（不滚动）
</Link>
{/* 自定义类名 */}
<Link
href="/contact"
className="nav-link"
activeClassName="active"
>
联系
</Link>
</>
)
}
如果需要链接到动态路由，可以使用对象形式：
import Link from 'next/link'
export default function ProductList() {
return (
<Link
href={{
pathname: '/products/[id]',
query: { id: '123' },
}}
>
产品详情
</Link>
)
}
除了使用 Link 组件，有时候我们需要在代码中控制导航，比如点击按钮后跳转、表单提交后跳转等。这时候就需要用到编程式导航。
useRouter Hook 提供了编程式导航的方法。需要注意的是，这个 Hook 只能在客户端组件中使用，记得在文件顶部加上 'use client'。
'use client'
import { useRouter } from 'next/navigation'
export default function NavigationButtons() {
const router = useRouter()
return (
<div>
<button onClick={() => router.push('/dashboard')}>
前往仪表盘
</button>
<button onClick={() => router.replace('/login')}>
替换到登录页
</button>
<button onClick={() => router.back()}>
返回
</button>
<button onClick={() => router.forward()}>
前进
</button>
<button onClick={() => router.refresh()}>
刷新
</button>
</div>
)
}
有时候我们需要在导航时携带查询参数，比如搜索关键词、分页信息等：
'use client'
import { useRouter, useSearchParams } from 'next/navigation'
export default function SearchNavigation() {
const router = useRouter()
const searchParams = useSearchParams()
function navigateWithParams() {
const params = new URLSearchParams(searchParams)
params.set('page', '2')
params.set('sort', 'asc')
router.push(`/search?${params.toString()}`)
}
return <button onClick={navigateWithParams}>搜索</button>
}
很多初学者会问，怎么在导航后执行一些操作？需要注意的是，router.push 是异步的，但它不返回 Promise，所以不能直接用 await。如果需要在导航后执行操作，可以使用 useEffect 监听路径变化。
'use client'
import { useRouter } from 'next/navigation'
export default function NavigationWithCallback() {
const router = useRouter()
function navigateWithCallback() {
router.push('/dashboard')
// 注意：push 是异步的，但没有 Promise
// 如需导航后执行操作，使用 useEffect 监听
}
return <button onClick={navigateWithCallback}>导航</button>
}
Next.js 提供了一些实用的路由 Hooks，能帮助我们获取路由信息。
获取当前路径名，这个在实现高亮菜单、面包屑导航等场景中很有用：
'use client'
import { usePathname } from 'next/navigation'
import Link from 'next/link'
export default function ActiveLink({
href,
children,
}: {
href: string
children: React.ReactNode
}) {
const pathname = usePathname()
const isActive = pathname === href
return (
<Link
href={href}
className={isActive ? 'text-blue-500 font-bold' : 'text-gray-700'}
>
{children}
</Link>
)
}
获取当前 URL 的查询参数，常用于读取搜索关键词、分页信息等：
'use client'
import { useSearchParams } from 'next/navigation'
export default function ProductList() {
const searchParams = useSearchParams()
const page = searchParams.get('page') || '1'
const sort = searchParams.get('sort') || 'desc'
return (
<div>
<p>当前页: {page}</p>
<p>排序: {sort}</p>
</div>
)
}
获取动态路由参数，比如文章的 slug、产品的 ID 等：
'use client'
import { useParams } from 'next/navigation'
export default function PostPage() {
const params = useParams()
const slug = params.slug as string
return (
<div>
<h1>文章: {slug}</h1>
</div>
)
}
下面分享几个在实际项目中常用的导航模式。
面包屑导航能让用户清楚自己当前所处的位置：
'use client'
import Link from 'next/link'
import { usePathname } from 'next/navigation'
export default function Breadcrumbs() {
const pathname = usePathname()
const segments = pathname.split('/').filter(Boolean)
return (
<nav className="flex gap-2">
<Link href="/">首页</Link>
{segments.map((segment, index) => {
const href = '/' + segments.slice(0, index + 1).join('/')
return (
<span key={href}>
<span className="mx-2">/</span>
<Link href={href}>{segment}</Link>
</span>
)
})}
</nav>
)
}
使用查询参数实现标签页切换是一个常见且实用的模式：
'use client'
import { useSearchParams } from 'next/navigation'
import Link from 'next/link'
export default function Tabs() {
const searchParams = useSearchParams()
const tab = searchParams.get('tab') || 'overview'
const tabs = [
{ id: 'overview', label: '概览' },
{ id: 'settings', label: '设置' },
{ id: 'analytics', label: '分析' },
]
return (
<div>
<div className="flex gap-4 border-b">
{tabs.map((t) => (
<Link
key={t.id}
href={`?tab=${t.id}`}
className={`pb-2 px-4 ${
tab === t.id
? 'border-b-2 border-blue-500 text-blue-500'
: 'text-gray-600'
}`}
>
{t.label}
</Link>
))}
</div>
{/* 标签页内容 */}
</div>
)
}
分页是列表页面必备的功能：
'use client'
import Link from 'next/link'
import { useSearchParams } from 'next/navigation'
export default function Pagination({ totalPages }: { totalPages: number }) {
const searchParams = useSearchParams()
const currentPage = Number(searchParams.get('page')) || 1
return (
<div className="flex gap-2">
{currentPage > 1 && (
<Link href={`?page=${currentPage - 1}`}>上一页</Link>
)}
{Array.from({ length: totalPages }, (_, i) => i + 1).map((page) => (
<Link
key={page}
href={`?page=${page}`}
className={
currentPage === page ? 'font-bold text-blue-500' : ''
}
>
{page}
</Link>
))}
{currentPage < totalPages && (
<Link href={`?page=${currentPage + 1}`}>下一页</Link>
)}
</div>
)
}
拦截路由是 Next.js 的一个高级特性，可以实现模态框效果：
'use client'
import { useRouter } from 'next/navigation'
import { useState } from 'react'
export default function ModalExample() {
const router = useRouter()
const [isOpen, setIsOpen] = useState(false)
function openModal(photoId: string) {
// 拦截导航，显示模态框
setIsOpen(true)
router.push(`/photos/${photoId}`)
}
function closeModal() {
setIsOpen(false)
router.back()
}
return (
<>
<button onClick={() => openModal('123')}>查看照片</button>
{isOpen && (
<div className="modal">
<button onClick={closeModal}>关闭</button>
<div>照片内容</div>
</div>
)}
</>
)
}
Next.js 的客户端导航是一个非常巧妙的设计，它的工作原理如下：
<a> 标签点击事件fetch 请求新页面的 JSON 数据这样做的好处是：
如果需要禁用客户端导航，可以这样：
import Link from 'next/link'
// 禁用 prefetch
<Link href="/about" prefetch={false}>
关于
</Link>
// 完全禁用客户端导航
<Link href="/external" scroll={false}>
外部链接
</Link>
使用 React 的 useTransition 可以实现页面切换时的加载状态：
'use client'
import { useRouter } from 'next/navigation'
import { useState, useTransition } from 'react'
export default function NavigationWithTransition() {
const router = useRouter()
const [isPending, startTransition] = useTransition()
function handleClick(path: string) {
startTransition(() => {
router.push(path)
})
}
return (
<nav>
<button
onClick={() => handleClick('/dashboard')}
disabled={isPending}
>
{isPending ? '加载中...' : '仪表盘'}
</button>
</nav>
)
}
如果你使用 framer-motion 这样的动画库，可以给导航添加流畅的过渡效果：
'use client'
import { motion } from 'framer-motion'
import Link from 'next/link'
import { usePathname } from 'next/navigation'
export default function AnimatedNav() {
const pathname = usePathname()
const links = [
{ href: '/', label: '首页' },
{ href: '/about', label: '关于' },
{ href: '/contact', label: '联系' },
]
return (
<nav>
{links.map((link) => (
<Link key={link.href} href={link.href}>
<motion.span
className={pathname === link.href ? 'active' : ''}
whileHover={{ scale: 1.1 }}
whileTap={{ scale: 0.95 }}
>
{link.label}
</motion.span>
</Link>
))}
</nav>
)
}
很多时候我们需要在用户访问某个页面前先检查一些条件，比如是否登录、是否有权限等。这时候可以使用中间件来实现重定向：
// middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
export function middleware(request: NextRequest) {
// 检查认证
const token = request.cookies.get('token')?.value
if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
return NextResponse.redirect(new URL('/login', request.url))
}
return NextResponse.next()
}
export const config = {
matcher: ['/dashboard/:path*', '/admin/:path*'],
}
在客户端也可以实现路由守卫：
'use client'
import { useRouter } from 'next/navigation'
import { useEffect } from 'react'
export default function ProtectedRoute() {
const router = useRouter()
useEffect(() => {
const isAuthenticated = checkAuth()
if (!isAuthenticated) {
router.push('/login')
}
}, [router])
return <div>受保护的内容</div>
}
这里分享几个在日常开发中特别实用的技巧。
实际开发中,声明式导航通常比命令式导航更清晰,所以我建议优先使用 Link 组件:
// 推荐这样做
<Link href="/about">关于</Link>
// 传统的写法也可以,但 Link 更好
<a href="/about">关于</a>
这个小细节很容易忽略——渲染动态链接列表时,记得给每个 Link 添加 key:
{posts.map((post) => (
<Link key={post.id} href={`/posts/${post.slug}`}>
{post.title}
</Link>
))}
这个技巧特别有用——给用户明确的加载反馈能大大提升用户体验:
'use client'
import { useRouter, usePathname } from 'next/navigation'
import { useState, useEffect } from 'react'
export default function LoadingIndicator() {
const router = useRouter()
const pathname = usePathname()
const [isLoading, setIsLoading] = useState(false)
useEffect(() => {
const handleStart = () => setIsLoading(true)
const handleComplete = () => setIsLoading(false)
router.events?.on('routeChangeStart', handleStart)
router.events?.on('routeChangeComplete', handleComplete)
return () => {
router.events?.off('routeChangeStart', handleStart)
router.events?.off('routeChangeComplete', handleComplete)
}
}, [router])
return isLoading ? <div>加载中...</div> : null
}
本节我们详细学习了 Next.js 的链接和导航系统，包括 Link 组件、编程式导航、路由 Hooks、各种导航模式等。掌握好这些知识，你就能构建出导航流畅、用户体验优秀的应用了。
如果你对本节内容有任何疑问，欢迎在评论区提出来，我们一起学习讨论。
本文基于 Claude Code 开源仓库的实际源码分析，代码路径来自
src/目录。
最近在阅读 Claude Code（CC）的开源源码，发现一个有意思的设计决策：CC 完全没有 RAG（Retrieval Augmented Generation），没有 embedding，没有向量数据库，没有语义检索。
但它能精准地在一个大型代码库里找到相关文件、记住你上周说过的事情、并且在复杂探索任务里自动派遣子 Agent。
这是怎么做到的？翻源码之后发现，CC 用了一套完全不同的路子。
RAG 的核心思路是：先把文档 embedding 成向量，然后用相似度检索找相关片段，塞进 prompt。
CC 完全不这样做。它的策略更"野蛮"——直接给 Claude 一堆搜索工具，让它自己决定搜什么：
Grep：正则搜代码内容Glob：文件名模式匹配Read：读具体文件Bash：跑 git log、find 等系统命令这就像把 Claude 变成了一个有 shell 权限的工程师，而不是一个查文档的问答机器人。
优点是精准——Grep 找到的就是真实代码，不存在语义偏差。缺点也很明显：项目大了之后，Grep 扛不住。
想象一个 5 万文件的 monorepo，你搜 handle，Grep 可能返回 200 个匹配。每个都是"精确"结果，但 Claude 的 context window 是有限的，200 个结果全塞进去既浪费 token 又干扰判断。
RAG 至少还有个相关性排序。Grep 的输出是按文件路径字母序排的——完全没有"哪个更重要"的概念。
CC 怎么解决这个问题？不是引入向量检索，而是 5 层策略的组合。
最简单粗暴也最有效的一层：让开发者手写项目的关键信息，放进 CLAUDE.md。
CC 会在每次会话加载这个文件，相当于给 Claude 一份"项目导览"。实质上是手动索引——开发者用自然语言告诉 Claude 哪些文件重要、架构是什么、哪些目录干什么用。
关于 CLAUDE.md 的写法和最佳实践，可以参考我之前的文章：CLAUDE.md 到底该怎么写？从「给 AI 的交接文档」说起。这里重点从源码角度看 CC 是怎么加载和使用它的。
源码 utils/claudemd.ts 的注释清楚地写出了 4 层加载逻辑：
/**
* Files are loaded in the following order:
*
* 1. Managed memory (/etc/claude-code/CLAUDE.md) - Global for all users
* 2. User memory (~/.claude/CLAUDE.md) - Private global for all projects
* 3. Project memory (CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md) - Checked into codebase
* 4. Local memory (CLAUDE.local.md) - Private project-specific instructions
*
* Files are loaded in reverse order of priority — the latest files are highest priority
* with the model paying more attention to them.
*/
越靠近当前目录的配置优先级越高，文件路径越深越重要。支持 @include 指令做文件嵌套——你可以把大型项目的文档拆成多个文件，按需 include。
本质：这是一个人工维护的语义索引，代替了 embedding 的"自动理解"。代价是需要开发者维护，收益是零幻觉、零延迟。
当 Claude 不知道具体文件在哪、只有模糊印象时（比如"有个处理权限的文件"），CC 提供了 FileIndex。
源码在 src/native-ts/file-index/index.ts，注释说明这是对 Rust NAPI 模块（基于 Helix 编辑器的 nucleo）的纯 TypeScript 重写。
下面这张流程图展示了 FileIndex 从收集文件到返回排序结果的完整过程：
整个流程分 4 步：ripgrep 收集文件列表 → 构建位图索引（26bit 字符位图实现 O(1) 快速排除）→ 模糊匹配 → 多维度评分排序返回 top-k。
核心评分常量：
// nucleo-style scoring constants (approximating fzf-v2 / nucleo bonuses)
const SCORE_MATCH = 16
const BONUS_BOUNDARY = 8 // 路径边界处匹配（/ \ - _ . 空格）
const BONUS_CAMEL = 6 // 驼峰命名边界
const BONUS_CONSECUTIVE = 4 // 连续字符匹配
const BONUS_FIRST_CHAR = 8 // 首字符匹配
const PENALTY_GAP_START = 3
const PENALTY_GAP_EXTENSION = 1
性能优化有几个亮点：
① Bitmap 预过滤（O(1) 拒绝）
每个文件路径在索引时预计算一个 26-bit bitmap，对应 a-z 每个字母是否出现：
private indexPath(i: number): void {
const lp = this.paths[i]!.toLowerCase()
this.lowerPaths[i] = lp
let bits = 0
for (let j = 0; j < len; j++) {
const c = lp.charCodeAt(j)
if (c >= 97 && c <= 122) bits |= 1 << (c - 97)
}
this.charBits[i] = bits
}
搜索时先用 (charBits[i] & needleBitmap) !== needleBitmap 做 O(1) 位运算过滤。注释说"broad queries like 'test' → 10%+ free win; 90%+ rejection for rare chars"。
② 异步分块构建，不阻塞主线程
const CHUNK_MS = 4 // 每次处理 ~4ms，然后 yield 给 event loop
// 5万文件 ~2ms on M-series，可能 15ms+ on older Windows hardware
// Chunk sizes are time-based (not count-based) so slow machines get smaller chunks
③ Top-K 维护，不全量排序
不是搜完所有文件再 sort，而是维护一个大小为 limit 的升序数组，用二分插入保持有序——只在找到更好匹配时才更新：
} else if (score > threshold) {
let lo = 0, hi = topK.length
while (lo < hi) {
const mid = (lo + hi) >> 1
if (topK[mid]!.fuzzScore < score) lo = mid + 1
else hi = mid
}
topK.splice(lo, 0, { path, fuzzScore: score })
topK.shift()
threshold = topK[0]!.fuzzScore
}
④ test 文件轻微降权
const finalScore = path.includes('test')
? Math.min(positionScore * 1.05, 1.0)
: positionScore
测试文件在大多数搜索场景下不是首要结果，加 5% 惩罚。细节但体贴。
智能大小写：
// Smart case: lowercase query → case-insensitive; any uppercase → case-sensitive
const caseSensitive = query !== query.toLowerCase()
和 vim / fzf 行为一致——全小写搜索忽略大小写，有大写字母就区分大小写。
FileIndex 缩小了候选文件集，Grep 在这些文件里做精确内容搜索，Read 读取完整文件。
这一层没有特别的算法，但有个重要原则：Claude 自己决定搜什么、怎么搜、搜多深。这是 Agentic 模式的核心——不是预先计算好"相关文档"再喂给模型，而是让模型在搜索过程中动态调整策略。
对于更复杂的探索任务，CC 有一个内置的 Explore Agent。当主 Agent 判断需要深度探索代码库时，会自动 spawn 这个子 Agent。
源码 src/tools/AgentTool/built-in/exploreAgent.ts：
export const EXPLORE_AGENT: BuiltInAgentDefinition = {
agentType: 'Explore',
// Ants get inherit to use the main agent's model;
// external users get haiku for speed
model: process.env.USER_TYPE === 'ant' ? 'inherit' : 'haiku',
// Explore is a fast read-only search agent — it doesn't need commit/PR/lint
// rules from CLAUDE.md. The main agent has full context and interprets results.
omitClaudeMd: true,
...
}
几个设计细节：
使用 Haiku 而不是 Sonnet：探索任务是读多写少，用便宜快速的 Haiku（外部用户）降低成本。Anthropic 内部员工（ant）用 inherit 继承主 Agent 的模型。
omitClaudeMd: true：Explore Agent 不加载项目的 CLAUDE.md——它只需要搜索能力，不需要了解项目的 commit 规范、PR 流程之类的。主 Agent 负责解读结果。
严格只读：禁用了 Edit、Write、NotebookEdit 工具，系统提示里用全大写强调：
=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
并行搜索：提示词明确要求"spawn multiple parallel tool calls for grepping and reading files"，通过并行 IO 提高探索速度。
随着对话进行，之前的搜索结果会越来越多，占用 context window。CC 有 Compaction 机制，将历史轮次压缩成摘要，清理不再需要的搜索结果。
这层解决的不是"怎么找到相关信息"，而是"如何保持 context 干净"——本质上是另一种形式的"索引维护"。
CC 有一个基于文件的记忆系统（~/.claude/projects/*/memory/），存储跨会话的上下文。有意思的是，它的记忆检索也不用 embedding。
源码 src/memdir/findRelevantMemories.ts：
const SELECT_MEMORIES_SYSTEM_PROMPT = `You are selecting memories that will be useful
to Claude Code as it processes a user's query. You will be given the user's query
and a list of available memory files with their filenames and descriptions.
Return a list of filenames for the memories that will clearly be useful
to Claude Code (up to 5). Only include memories that you are certain will be helpful.`
export async function findRelevantMemories(
query: string,
memoryDir: string,
signal: AbortSignal,
recentTools: readonly string[] = [],
alreadySurfaced: ReadonlySet<string> = new Set(),
): Promise<RelevantMemory[]> {
const memories = await scanMemoryFiles(memoryDir, signal)
const selectedFilenames = await selectRelevantMemories(
query, memories, signal, recentTools,
)
// ...
}
机制很简单：Sonnet 做 side query，输入是用户的 query + 所有记忆文件的 frontmatter（文件名 + description 字段），输出是最多 5 个相关文件名。
const result = await sideQuery({
model: getDefaultSonnetModel(), // Sonnet
system: SELECT_MEMORIES_SYSTEM_PROMPT,
messages: [{ role: 'user', content: `Query: ${query}\n\nAvailable memories:\n${manifest}` }],
max_tokens: 256, // 只需要返回文件名列表，非常轻量
output_format: { type: 'json_schema', ... },
})
一个有趣的细节：如果 Claude 最近在用某个工具（比如 mcp__X__spawn），记忆选择会主动过滤掉这个工具的"使用文档"类记忆：
// When Claude Code is actively using a tool (e.g. mcp__X__spawn),
// surfacing that tool's reference docs is noise — the conversation
// already contains working usage.
// DO still select memories containing warnings, gotchas, or known issues
// about those tools — active use is exactly when those matter.
const toolsSection = recentTools.length > 0
? `\n\nRecently used tools: ${recentTools.join(', ')}`
: ''
逻辑：你都在用这个工具了，再给你这个工具的使用说明是噪声。但如果记忆里有"这个工具的已知坑"，反而应该优先展示。
src/memdir/memoryAge.ts 有个精妙的设计——记忆文件会带着年龄信息展示给主模型：
export function memoryFreshnessText(mtimeMs: number): string {
const d = memoryAgeDays(mtimeMs)
if (d <= 1) return ''
return (
`This memory is ${d} days old. ` +
`Memories are point-in-time observations, not live state — ` +
`claims about code behavior or file:line citations may be outdated. ` +
`Verify against current code before asserting as fact.`
)
}
注释说明了动机："user reports of stale code-state memories (file:line citations to code that has since changed) being asserted as fact — the citation makes the stale claim sound more authoritative, not less."
这是一个真实踩坑后的修复。记忆里写着"AuthService 在 src/auth.ts:142 处理登录"，但那个文件早就重构了，Claude 还一本正经地引用这个"出处"。解法不是引入更复杂的记忆管理，而是直接告诉模型"这条记忆 47 天前写的，信之前自己核实一下"。
CC 的方案不是万能的，几个场景下 RAG 仍然是更好的选择：
1. 超大非结构化文档库：如果你有 10 万篇 Confluence 页面需要检索，让 AI 用 Grep 搜不现实。RAG 的向量索引在这个规模下有明显优势。
2. 语义相似而非关键词匹配：搜"用户登录相关的代码"，Grep 能找到，但"身份验证"、"session 管理"、"OAuth 流程"这些语义相关但关键词不同的内容，向量检索更擅长。
3. 多语言混合文档：中文查询匹配英文文档，RAG 的向量空间天然支持跨语言语义对齐。
4. 无法给 AI 工具权限的场景：如果你的系统无法给 AI 直接执行搜索命令的权限（安全限制），RAG 是合理的替代。
CC 的场景是：代码库 + 有工具执行权限的 Agent。在这个场景下，精确搜索 + 分层策略比 embedding 检索更直接、更可控、更省成本。
CC 不用 RAG 的根本原因是：它不需要。
RAG 解决的问题是"如何从大量文档里找到相关片段，塞进有限的 context window"。CC 换了个思路——不预先计算相关性，而是让模型带着搜索工具自己探索，用 FileIndex 做模糊排序，用 CLAUDE.md 做手动索引，用 Compaction 管理 context 大小，用 Haiku 子 Agent 分担搜索负担。
每一层都很简单，但组合在一起，覆盖了代码库探索的大部分场景。
这让我想到一个更广泛的设计原则：不要为了用技术而用技术。Embedding + 向量数据库是一套完整的基础设施，引入它就要维护它、监控它、调 retrieval 参数。在能用更简单方案解决问题的情况下，复杂方案只是债务。
CC 开源源码解读（二）：上下文压缩是怎么做的？
CC 的 Compaction 机制非常有意思——不是简单的截断，而是一套分层压缩策略。在长对话中，CC 如何判断什么信息可以丢弃、什么必须保留？如何在压缩信息量和保持 Agent 连贯性之间取得平衡？
源码层面深挖，下篇见。
如果你也在研究 CC 源码，欢迎评论区交流。
源码仓库：claude-code GitHub
📢 宣言：每周更新国外论坛的前端热门文章，推荐大家阅读/翻译，紧跟时事，掌握前端技术动态，也为写作或突破新领域提供灵感~
欢迎大家访问：github.com/TUARAN/fron… 顺手点个 ⭐ star 支持，是我们持续输出的续航电池🔋✨！
在线网址：frontendweekly.cn/
💬 推荐语
本期更像一次很清晰的信号汇总：浏览器平台继续补齐“过去需要框架和脚本硬扛”的能力，而工程现实也在继续逼我们重新看待安全、可维护性与交互边界。
一边是平台层继续前进。Chrome 147 带来 element-scoped view transitions，setHTML() 这样的安全 API 开始走向更实用的位置，Shadow DOM 的 delegatesFocus、Anchor Positioning、自动进入视频画中画、文本缩放支持等话题，也都在说明 Web 平台正在一点点把历史上的“边缘痛点”收回来。
另一边，工程和体验问题并没有因为平台变强而自动消失。DevTools 继续强化调试能力，Three.js Conf 网站与 Codrops 的动效案例在拉高体验上限，Deno Sandbox、开发者工具和 AI/平台协作方向的文章，则提醒我们：现代前端已经不只是框架选型，而是在同时处理能力暴涨、交互复杂化与安全边界重构。
如果把这期压缩成一句话，那就是：前端的下一阶段，拼的不是“会不会追新”，而是能不能准确判断哪些复杂度应该交给平台，哪些还得自己治理。
delegatesFocus 是一个典型“看起来很小，实际影响组件可用性和可访问性”的平台细节。details 配合 @scope 做层级菜单，体现了原生 HTML 与现代 CSS 组合拳的威力。从 setHTML()、element-scoped view transitions、delegatesFocus 到 Anchor Positioning，这期最值得记住的不是某一个孤立新特性，而是一个越来越明确的趋势：Web 平台正在主动接管更多曾经只能靠框架、脚本和经验兜底的问题。
但平台变强并不等于工程变简单。安全边界、组件可用性、调试复杂度、交互组织方式，依旧需要团队做出判断。真正有价值的前端工作，越来越不是追着每个新词跑，而是看清哪些能力已经成熟到值得纳入日常体系，哪些地方又仍然必须谨慎设计。
上个月我接了一个NFT铸造平台的前端开发，项目要求是用户连接钱包后，页面需要实时显示两个关键数据：当前钱包地址的铸造数量（userMintedCount）和该NFT项目的总铸造量（totalSupply）。合约已经由团队的其他成员部署好了，事件也定义得很清楚：Minted(address indexed minter, uint256 tokenId)。
一开始我觉得这很简单——不就是监听事件嘛。但真正做起来才发现，从“能工作”到“稳定、实时、高性能”之间，隔着好几个大坑。我最开始用了最笨的轮询方式，每5秒调用一次合约的totalSupply()和查询用户的余额，结果就是页面卡顿、数据更新不及时，用户体验很差。我意识到必须用真正的事件监听，但该选哪种方案？怎么处理多链？断开监听怎么办？这一路踩的坑，今天我就完整记录下来。
我的第一反应是直接用ethers.js的contract.on方法。写了个简单的测试：
const contract = new ethers.Contract(address, abi, provider);
contract.on('Minted', (minter, tokenId) => {
console.log(`用户 ${minter} 铸造了 token #${tokenId}`);
// 更新状态...
});
在本地测试网上跑得挺好。但一上主网测试就出问题了：当用户切换钱包账户时，之前账户的监听器没有正确清理，导致事件重复触发。更麻烦的是，我们的DApp需要支持多链（Ethereum、Polygon、Arbitrum），不同链的Provider和合约实例管理起来很混乱。
然后我尝试了wagmi的useContractEvent（这是wagmi v1的写法），发现它确实帮我处理了React生命周期内的监听器清理，但它在用户切换链时表现不稳定，有时会漏掉事件。而且项目用的是wagmi v2，API已经有了变化。
经过一番排查，我确定了几个必须解决的核心问题：
在wagmi v2中，监听合约事件的主要Hook是useWatchContractEvent。与v1的useContractEvent不同，它更专注于“监听”这一单一职责，并且返回的是undefined（监听行为是副作用），这让它在组合使用时更清晰。
我首先实现了最基本的监听：
import { useWatchContractEvent } from 'wagmi';
function MintTracker() {
const { chain } = useAccount();
useWatchContractEvent({
address: NFT_CONTRACT_ADDRESS[chain?.id || 1], // 根据当前链选择合约地址
abi: NFT_ABI,
eventName: 'Minted',
onLogs(logs) {
logs.forEach((log) => {
const [minter, tokenId] = log.args;
console.log('监听到铸造事件:', minter, tokenId);
// 这里更新状态
});
},
});
return <div>监听中...</div>;
}
这里有个坑：useWatchContractEvent默认只在组件挂载时开始监听。但如果合约地址是动态的（比如根据链ID变化），当链切换后，监听的目标合约地址不会自动更新！这意味着用户切换到Polygon后，还在监听Ethereum上的旧合约。
为了解决链切换问题，我需要确保监听器在链变化时重新建立。wagmi的useWatchContractEvent本身不会自动处理这个，但我们可以利用它的enabled参数和依赖数组：
import { useAccount, useWatchContractEvent } from 'wagmi';
function MintTracker() {
const { chain, address: userAddress } = useAccount();
const [totalSupply, setTotalSupply] = useState(0);
const [userMinted, setUserMinted] = useState(0);
// 获取当前链对应的合约地址
const contractAddress = chain?.id ? NFT_CONTRACT_ADDRESS[chain.id] : undefined;
// 监听Minted事件 - 只有合约地址存在时才启用监听
useWatchContractEvent({
address: contractAddress,
abi: NFT_ABI,
eventName: 'Minted',
enabled: !!contractAddress, // 关键：地址不存在时不建立监听
onLogs(logs) {
// 处理事件日志
handleMintLogs(logs);
},
});
const handleMintLogs = useCallback((logs: any[]) => {
logs.forEach((log) => {
const [minter, tokenId] = log.args;
// 更新总供应量（每次铸造+1）
setTotalSupply(prev => prev + 1);
// 如果铸造者是当前用户，更新用户铸造数量
if (minter.toLowerCase() === userAddress?.toLowerCase()) {
setUserMinted(prev => prev + 1);
}
});
}, [userAddress]);
return (
<div>
<p>总铸造量: {totalSupply}</p>
<p>你的铸造数量: {userMinted}</p>
</div>
);
}
注意这个细节：我用了enabled: !!contractAddress来确保只有合约地址有效时才建立监听。这样当用户断开钱包连接或切换到不支持的链时，监听会自动停止。
事件监听只能捕获未来的事件，但页面加载时我们需要显示当前的状态。所以还需要在组件加载时获取初始值，并在每次事件触发时更新。
我创建了一个自定义Hook来封装这个逻辑：
import { useContractRead, useWatchContractEvent } from 'wagmi';
import { useEffect } from 'react';
export function useNFTMintTracker() {
const { chain, address: userAddress } = useAccount();
const contractAddress = chain?.id ? NFT_CONTRACT_ADDRESS[chain.id] : undefined;
// 1. 获取初始的总供应量
const {
data: totalSupplyData,
refetch: refetchTotalSupply
} = useContractRead({
address: contractAddress,
abi: NFT_ABI,
functionName: 'totalSupply',
enabled: !!contractAddress,
});
// 2. 获取用户的初始铸造数量（需要合约有相应的view函数）
const {
data: userBalanceData,
refetch: refetchUserBalance
} = useContractRead({
address: contractAddress,
abi: NFT_ABI,
functionName: 'balanceOf',
args: userAddress ? [userAddress] : undefined,
enabled: !!contractAddress && !!userAddress,
});
// 3. 监听Minted事件
useWatchContractEvent({
address: contractAddress,
abi: NFT_ABI,
eventName: 'Minted',
enabled: !!contractAddress,
onLogs(logs) {
// 每次有铸造事件时，重新获取最新数据
refetchTotalSupply();
if (userAddress) {
refetchUserBalance();
}
},
});
// 4. 当链或用户地址变化时，重新获取数据
useEffect(() => {
if (contractAddress) {
refetchTotalSupply();
if (userAddress) {
refetchUserBalance();
}
}
}, [chain?.id, userAddress, contractAddress]);
return {
totalSupply: totalSupplyData ? Number(totalSupplyData) : 0,
userMinted: userBalanceData ? Number(userBalanceData) : 0,
isLoading: !totalSupplyData && !userBalanceData
};
}
这里有个重要的设计决策：我选择在监听到事件时重新调用refetch函数，而不是直接在前端计算+1。为什么？因为可能有多个用户同时铸造，直接+1可能导致数据不一致。重新从链上查询虽然多了一次调用，但保证了数据的准确性。
上面的方案在大多数情况下够用了。但在我们的项目中，还有一个需求：无论用户当前在哪个页面，只要发生了铸造，页面右上角的一个全局徽章数字都需要更新。
这意味着我需要一个“全局”的事件监听，而不是组件级别的。我最终选择了在wagmi的Provider层面设置监听：
// 在_app.tsx或类似的根组件中
import { createConfig, WagmiProvider } from 'wagmi';
import { http } from 'wagmi';
import { mainnet, polygon } from 'wagmi/chains';
// 创建自定义的wagmi配置
const config = createConfig({
chains: [mainnet, polygon],
transports: {
[mainnet.id]: http(),
[polygon.id]: http(),
},
// 这里可以添加事件监听
});
// 然后在React组件外部设置全局监听器
let unsubscribe: (() => void) | undefined;
// 一个工具函数来管理全局监听
export function setupGlobalMintListener(config: any) {
// 清理之前的监听器
if (unsubscribe) {
unsubscribe();
}
// 为每条链都设置监听
config.chains.forEach((chain: any) => {
const contractAddress = NFT_CONTRACT_ADDRESS[chain.id];
if (contractAddress) {
const publicClient = config.getPublicClient({ chainId: chain.id });
// 监听事件
unsubscribe = publicClient.watchContractEvent({
address: contractAddress,
abi: NFT_ABI,
eventName: 'Minted',
onLogs: (logs) => {
// 这里可以更新全局状态，比如使用zustand或Redux
console.log('全局监听到铸造事件:', logs);
},
});
}
});
}
注意：这种全局监听要谨慎使用，因为它不在React生命周期内，需要手动管理清理。我把它用在确实需要跨组件共享状态的场景。
下面是一个完整的、可直接运行的组件示例：
import React, { useCallback } from 'react';
import { useAccount, useContractRead, useWatchContractEvent } from 'wagmi';
// NFT合约ABI片段
const NFT_ABI = [
{
"anonymous": false,
"inputs": [
{ "indexed": true, "name": "minter", "type": "address" },
{ "indexed": false, "name": "tokenId", "type": "uint256" }
],
"name": "Minted",
"type": "event"
},
{
"inputs": [],
"name": "totalSupply",
"outputs": [{ "name": "", "type": "uint256" }],
"stateMutability": "view",
"type": "function"
},
{
"inputs": [{ "name": "owner", "type": "address" }],
"name": "balanceOf",
"outputs": [{ "name": "", "type": "uint256" }],
"stateMutability": "view",
"type": "function"
}
] as const;
// 各链的合约地址
const NFT_CONTRACT_ADDRESS: Record<number, `0x${string}`> = {
1: '0x...', // Ethereum主网
137: '0x...', // Polygon
42161: '0x...', // Arbitrum
};
interface MintTrackerProps {
showUserStats?: boolean;
}
export default function MintTracker({ showUserStats = true }: MintTrackerProps) {
const { chain, address: userAddress } = useAccount();
// 获取当前链的合约地址
const contractAddress = chain?.id ? NFT_CONTRACT_ADDRESS[chain.id] : undefined;
// 读取总供应量
const {
data: totalSupplyData,
refetch: refetchTotalSupply,
isLoading: isLoadingTotalSupply
} = useContractRead({
address: contractAddress,
abi: NFT_ABI,
functionName: 'totalSupply',
enabled: !!contractAddress,
});
// 读取用户余额
const {
data: userBalanceData,
refetch: refetchUserBalance,
isLoading: isLoadingUserBalance
} = useContractRead({
address: contractAddress,
abi: NFT_ABI,
functionName: 'balanceOf',
args: userAddress ? [userAddress] : undefined,
enabled: !!contractAddress && !!userAddress && showUserStats,
});
// 处理铸造事件的回调
const handleMintLogs = useCallback((logs: any[]) => {
console.log('监听到铸造事件，数量:', logs.length);
// 重新获取最新数据
refetchTotalSupply();
if (userAddress && showUserStats) {
refetchUserBalance();
}
// 可以在这里添加通知或动画效果
if (logs.length > 0) {
const latestLog = logs[logs.length - 1];
const [minter, tokenId] = latestLog.args;
console.log(`最新铸造: ${minter} 铸造了 #${tokenId}`);
}
}, [refetchTotalSupply, refetchUserBalance, userAddress, showUserStats]);
// 监听Minted事件
useWatchContractEvent({
address: contractAddress,
abi: NFT_ABI,
eventName: 'Minted',
enabled: !!contractAddress,
onLogs: handleMintLogs,
});
// 加载状态
if (isLoadingTotalSupply) {
return <div>加载数据中...</div>;
}
// 不支持的网络
if (!contractAddress) {
return <div>请切换到支持的网络（Ethereum、Polygon或Arbitrum）</div>;
}
return (
<div className="mint-tracker">
<div className="stats">
<div className="stat">
<h3>总铸造量</h3>
<p className="value">{totalSupplyData?.toString() || '0'}</p>
</div>
{showUserStats && userAddress && (
<div className="stat">
<h3>你的铸造数量</h3>
<p className="value">{userBalanceData?.toString() || '0'}</p>
</div>
)}
</div>
<div className="status">
<span className="indicator active"></span>
<span>实时监听已启用</span>
</div>
</div>
);
}
监听器泄露导致重复触发
useWatchContractEvent的依赖项变化时，旧的监听器没有立即清理，新旧监听器短暂共存enabled参数正确设置，当不应监听时立即禁用。另外，使用useCallback包装回调函数，避免每次渲染创建新函数链切换后监听不更新
useWatchContractEvent的地址参数变化时，不会自动重新建立监听enabled参数和contractAddress依赖控制，地址变化时先禁用再重新启用监听RPC节点限制导致监听中断
大量事件导致性能问题
经过这一轮折腾，我最大的收获是：Web3前端的事件监听不是简单的“监听就行”，需要考虑React生命周期、链切换、性能、错误处理等方方面面。wagmi v2的useWatchContractEvent是个好工具，但它不是魔法，需要正确理解它的行为。对于更复杂的场景，可能还需要结合viem的底层API或自定义Provider监听。下次我准备深入研究一下如何优化大量事件的处理性能，这又是一个值得记录的坑。
想象一下，你正在布置一个房间（你的网页）。家具（HTML 元素）默认会按照购买顺序依次摆放——这就是文档流。但有时候，你想让台灯悬浮在角落，让时钟始终挂在墙上，或者让某个装饰在滚动时"粘"在特定位置。
这时，你就需要 CSS 的 position 属性——它就像是给元素发放的"特权通行证"，让它们突破常规布局的限制！
在深入 position 之前，必须理解这个核心概念：
📋 文档流（Document Flow）
├── 块级元素：从上到下垂直排列
├── 行内元素：从左到右水平排列
└── 元素默认按 HTML 代码顺序依次摆放
关键点：position 的本质就是控制元素是否脱离文档流以及如何定位。
.element {
position: static; /* 默认值，通常可以省略 */
}
| 特性 | 说明 |
|---|---|
| 文档流 | ✅ 不脱离 |
| top/left/right/bottom | ❌ 不生效 |
| z-index | ❌ 不生效 |
| 使用场景 | 默认状态，无需特殊定位时 |
<!-- 示例 -->
<div class="box">我是 static，按正常顺序排列</div>
.element {
position: relative;
top: 20px; /* 向下偏移 20px */
left: 30px; /* 向右偏移 30px */
}
| 特性 | 说明 |
|---|---|
| 文档流 | ✅ 不脱离（原位置保留） |
| 参照物 | 自身原始位置 |
| z-index | ✅ 生效 |
| 使用场景 | 微调位置、作为 absolute 的参照父元素 |
<style>
.container {
position: relative; /* 重要！作为子元素 absolute 的参照 */
width: 300px;
height: 200px;
background: #e0e0e0;
}
.child {
position: relative;
top: 10px;
left: 10px;
background: #4CAF50;
color: white;
}
</style>
<div class="container">
<div class="child">相对定位 - 相对于自己原位置移动</div>
</div>
💡 经典用法：
relative + absolute组合，父元素设 relative，子元素设 absolute 实现局部定位
.element {
position: absolute;
top: 0;
right: 0;
}
| 特性 | 说明 |
|---|---|
| 文档流 | ❌ 脱离（不占原位置） |
| 参照物 | 最近的非 static 定位祖先元素 |
| 无参照时 | 相对于初始包含块（通常是 viewport） |
| z-index | ✅ 生效 |
| 使用场景 | 弹窗、角标、悬浮按钮、下拉菜单 |
<style>
.card {
position: relative; /* 关键：建立定位上下文 */
width: 250px;
height: 150px;
background: #fff;
border: 1px solid #ddd;
}
.badge {
position: absolute;
top: -10px;
right: -10px;
background: #f44336;
color: white;
padding: 5px 10px;
border-radius: 50%;
}
</style>
<div class="card">
<span class="badge">NEW</span>
<p>卡片内容...</p>
</div>
⚠️ 常见坑点：absolute 元素找不到定位祖先时，会相对于页面定位，导致布局错乱！
.element {
position: fixed;
top: 0;
left: 0;
width: 100%;
}
| 特性 | 说明 |
|---|---|
| 文档流 | ❌ 脱离 |
| 参照物 | 浏览器视口（viewport） |
| 滚动行为 | 固定不动 |
| z-index | ✅ 生效 |
| 使用场景 | 导航栏、回到顶部按钮、广告横幅 |
<style>
.navbar {
position: fixed;
top: 0;
left: 0;
width: 100%;
height: 60px;
background: #333;
color: white;
z-index: 1000; /* 确保在最上层 */
}
.back-to-top {
position: fixed;
bottom: 30px;
right: 30px;
width: 50px;
height: 50px;
background: #2196F3;
color: white;
border-radius: 50%;
}
</style>
<nav class="navbar">固定导航栏 - 滚动时始终在顶部</nav>
<button class="back-to-top">↑</button>
🔍 注意：在移动端需要注意视口高度和键盘弹出时的影响
.element {
position: sticky;
top: 0; /* 必须指定阈值！ */
}
| 特性 | 说明 |
|---|---|
| 文档流 | ✅ 不脱离（阈值前） |
| 行为 | relative + fixed 的结合体 |
| 阈值 | 必须设置 top/bottom/left/right 之一 |
| 使用场景 | 表格表头、侧边导航、吸顶效果 |
<style>
.sticky-header {
position: sticky;
top: 0; /* 滚动到距离顶部 0px 时固定 */
background: #1976D2;
color: white;
padding: 15px;
z-index: 100;
}
.content {
height: 2000px; /* 制造滚动空间 */
padding: 20px;
}
</style>
<header class="sticky-header">
📌 粘性标题 - 滚动时吸顶
</header>
<div class="content">
<p>向下滚动查看效果...</p>
</div>
⚠️ sticky 不生效的常见原因：
- 父元素有
overflow: hidden/auto/scroll- 没有设置 top/left/right/bottom 阈值
- 父元素高度不足以产生滚动
| 属性值 | 脱离文档流 | 参照物 | z-index | 典型场景 |
|---|---|---|---|---|
static |
❌ | - | ❌ | 默认布局 |
relative |
❌ | 自身原位置 | ✅ | 微调、定位上下文 |
absolute |
✅ | 最近非 static 祖先 | ✅ | 弹窗、角标 |
fixed |
✅ | 视口 | ✅ | 导航栏、悬浮按钮 |
sticky |
⚠️ 条件脱离 | 滚动容器 | ✅ | 吸顶、表格表头 |
.product-card {
position: relative;
}
.sale-badge {
position: absolute;
top: 10px;
left: 10px;
background: #ff5722;
color: white;
padding: 4px 8px;
border-radius: 4px;
}
.modal-overlay {
position: fixed;
top: 0;
left: 0;
width: 100%;
height: 100%;
background: rgba(0,0,0,0.5);
}
.modal-content {
position: absolute;
top: 50%;
left: 50%;
transform: translate(-50%, -50%);
background: white;
padding: 30px;
border-radius: 8px;
}
.sidebar {
position: sticky;
top: 80px; /* 距离顶部 80px 开始固定 */
height: calc(100vh - 80px);
overflow-y: auto;
}
| 问题 | 原因 | 解决方案 |
|---|---|---|
| absolute 乱跑 | 找不到定位祖先 | 给父元素加 position: relative
|
| sticky 不生效 | 父元素 overflow 限制 | 检查并调整父元素 overflow |
| fixed 被遮挡 | z-index 层级问题 | 提高 z-index 值 |
| 定位偏移不准 | 未考虑 border/padding | 使用 box-sizing: border-box |
relative 父容器包裹 absolute 子元素position 是 CSS 布局的基石之一，掌握它能让你的页面从"规整"变得"灵动"。记住核心要点：
最好的学习方式就是动手实践！打开你的代码编辑器，创建几个测试页面，亲自体验每种定位的效果变化。
你熟悉 Next.js，熟悉文件路由、布局、SSR。你大概也熟悉那些痛点：Server Components vs Client Components，满屏的 "use client"，莫名其妙的 hydration 错误，还有你一行业务代码没写就已经 233 KB 的客户端包。
Pareto 提供同样的 SSR 模式——但没有这些复杂性。标准 React 组件，Vite 替代 Webpack/Turbopack，客户端包只有 62 KB。这篇文章详细对比从 Next.js 切到 Pareto 时，什么变了，什么不变。
Next.js（App Router）： 每个组件默认是 Server Component。想用 useState？加 "use client"。数据获取通过 async server component 或者 generateMetadata。你无时无刻不在思考 server/client 边界。
Pareto： 每个组件都是普通 React 组件，同时运行在服务端和客户端。数据获取在 loader.ts 文件中完成——借鉴了 Remix 的模式。没有 "use client" 指令，因为根本不存在 Server Component / Client Component 的划分。
Next.js 心智模型： "这是 Server Component 还是 Client Component？"
Pareto 心智模型： "这是数据还是 UI？"
如果你熟悉 Next.js App Router 的约定，Pareto 的路由会立刻上手：
| Next.js | Pareto | 用途 |
|---|---|---|
page.tsx |
page.tsx |
路由组件 |
layout.tsx |
layout.tsx |
包裹布局 |
| — | loader.ts |
服务端数据获取 |
loading.tsx |
Suspense + <Await>
|
加载状态 |
error.tsx |
ParetoErrorBoundary |
错误处理 |
not-found.tsx |
not-found.tsx |
404 页面 |
route.ts |
route.ts |
API 端点 |
generateMetadata |
head.tsx |
Meta 标签 |
最大的区别：Pareto 用独立的 loader.ts 文件做数据获取，而不是把页面组件变成 async。
Next.js（App Router）：
// app/dashboard/page.tsx（server component）
export default async function Dashboard() {
const stats = await db.getStats()
return <h1>{stats.total} users</h1>
}
Pareto：
// app/dashboard/loader.ts
import type { LoaderContext } from '@paretojs/core'
export function loader(ctx: LoaderContext) {
return { stats: db.getStats() }
}
// app/dashboard/page.tsx
import { useLoaderData } from '@paretojs/core'
export default function Dashboard() {
const { stats } = useLoaderData<{ stats: { total: number } }>()
return <h1>{stats.total} users</h1>
}
两个文件替代一个，但分离是有意为之：数据获取是显式的、可测试的，永远不与渲染逻辑混在一起。组件是标准 React——没有 async，没有 await，没有 server-only 限制。
defer() 替代 Suspense 体操Next.js： 流式渲染需要把页面拆分成 server 和 client 组件，协调 loading.tsx 边界，理解哪些组件会阻塞首次渲染。
Pareto： 在 loader 中调用 defer()，用 <Await> 包裹慢数据。搞定。
// app/dashboard/loader.ts
import { defer } from '@paretojs/core'
export async function loader() {
const userCount = await getUserCount() // 先解析快数据
return defer({
userCount, // 已解析——立即发送
activityFeed: getActivityFeed(), // 慢——流式传输
analytics: getAnalytics(), // 更慢——稍后流式传输
})
}
// app/dashboard/page.tsx
import { useLoaderData, Await } from '@paretojs/core'
export default function Dashboard() {
const { userCount, activityFeed, analytics } = useLoaderData()
return (
<div>
<h1>{userCount} users</h1>
<Await resolve={activityFeed} fallback={<Skeleton />}>
{(feed) => <ActivityList items={feed} />}
</Await>
<Await resolve={analytics} fallback={<ChartSkeleton />}>
{(data) => <AnalyticsChart data={data} />}
</Await>
</div>
)
}
每个 <Await> 创建独立的 Suspense 边界。快数据立即渲染，慢数据逐步流入。初始 SSR 和客户端导航行为一致（Pareto 4.0 通过 NDJSON 流式传输实现）。
Next.js：
export async function generateMetadata({ params }) {
const post = await getPost(params.id)
return { title: post.title, description: post.excerpt }
}
Pareto：
// app/blog/[id]/head.tsx
export default function Head({ loaderData }: { loaderData: { post: Post } }) {
return (
<>
<title>{loaderData.post.title}</title>
<meta name="description" content={loaderData.post.excerpt} />
<meta property="og:title" content={loaderData.post.title} />
</>
)
}
就是一个 React 组件。可以用条件逻辑、组合共享组件、渲染任何合法的 <head> 内容。Head 组件从根布局到页面依次合并——最深层路由的重复标签优先。
Next.js 对状态管理没有意见。你自己装 Redux、Zustand、Jotai，然后自己搞定 SSR hydration。
Pareto 内置 defineStore()，集成 Immer：
import { defineStore } from '@paretojs/core/store'
const { useStore, getState, setState } = defineStore((set) => ({
items: [] as CartItem[],
total: 0,
addItem: (item: CartItem) => set((d) => {
d.items.push(item)
d.total += item.price
}),
}))
SSR hydration 全自动。服务端定义的状态自动序列化并在客户端恢复，不需要任何手动的 dehydrate / rehydrate 样板代码。
Next.js： next.config.js 框架配置 + 单独的 Webpack/Turbopack 定制 + 可能还有 middleware.ts + 环境变量约定。
Pareto： 一个 pareto.config.ts：
import type { ParetoConfig } from '@paretojs/core'
const config: ParetoConfig = {
configureVite(config) {
// 标准 Vite 配置——你的插件直接能用
return config
},
configureServer(app) {
// 标准 Express app——加任何中间件
app.use(cors())
},
}
export default config
没有框架魔法。底层就是 Vite 和 Express，完全可控。
我们在 CI 中跑自动化基准测试，在相同硬件上对比 Pareto 和 Next.js：
换算成基础设施：一个需要 2,000 req/s 的页面，Pareto 需要 1 台服务器，Next.js 需要 6 台。完整基准测试数据：paretojs.tech/blog/benchm…
公开透明很重要。Pareto 没有的东西：
"use client"。这是设计选择：loader 模式更简单，覆盖 95% 的场景。<Image> 组件。用标准 <img> + CDN。configureServer() 中的 Express 中间件替代。如果你在做内容驱动的营销站需要 ISR，Next.js 仍然是对的选择。如果你在做数据驱动的应用、性能和简洁性很重要，Pareto 值得切换。
npx create-pareto@latest my-app — 创建新项目loader.ts + 标准组件"use client" 指令 — 不需要了generateMetadata 迁移到 head.tsx 组件loading.tsx 替换为 defer() + <Await> 流式渲染next/link 换成 @paretojs/core 的 Link
pareto.config.ts 的 configureVite()
npx create-pareto@latest my-app
cd my-app && npm install && npm run dev
最近 Hacker News 上有篇帖子火了，365 票——讲的是怎么配置 .claude/ 文件夹，让 Claude Code 更懂你的项目。
评论区一片热闹，大家在分享自己的 CLAUDE.md 怎么写、规则怎么定、怎么让 AI 更听话。有人贴出了自己精心调教过的配置文件，有人在讨论 .cursorrules 和 CLAUDE.md 到底哪个优先级更高。
但我看完之后的第一反应不是"赶紧学"，而是一阵恍惚：
这些人在手写配置文件，教 AI 认识自己的项目。而我写了10年的 C++ 模块库，AI 连它的存在都不知道。
不是我没有积累，恰恰相反——我有太多积累了。多到我自己都搞不清楚某个能力到底在哪个模块里。
我有一个 C++ 项目叫 hbcore，维护了快10年。
这不是什么玩具项目。它是一个完整的流媒体技术栈——音视频采集、硬件编解码、网络传输、RTSP/RTMP/WebRTC/GB28181 四种协议栈、HLS 分片、MP4 解析、录制回放、屏幕捕获、混流引擎……26个模块，覆盖了从设备采集到服务端推流的全链路。
上个月我用 repo-scan（一个我写的 Claude Code / Codex CLI Skill，能对整个代码仓库做逐文件深度审计）做了一次全量分析。结果长这样：
| 模块 | 源文件数 | 体积 | 技术栈 | 审计判决 |
|---|---|---|---|---|
| base | 54 | 337 KB | C/C++ | 提纯合并 |
| protocol_webrtc | 44 | 779 KB | C/C++ | 重塑提取 |
| output_rtmp | 35 | 526 KB | C/C++ | 重塑提取 |
| rtsp_server | 85 | 262 KB | C/C++ | 提纯合并 |
| mp4_parser | 62 | 160 KB | C/C++ | 重塑提取 |
| capture_device | 13 | 300 KB | C/C++ | 重塑提取 |
| base_codec | 23 | 153 KB | C/C++ | 提纯合并 |
| protocol_gb28181 | 23 | 324 KB | C/C++ | 重塑提取 |
| …（共26个模块） |
26个模块，10万+行代码。光是
base一个模块就被其他23个模块依赖——它是整个技术栈的地基。
下图是repo-scan 生成的HTML报告：
但你猜怎么着？
这个项目没有 CLAUDE.md。
没有 .cursorrules，没有任何让 AI 工具理解项目结构的元数据文件。
这意味着什么？意味着当我用 Claude Code 或 Cursor 开一个新项目、需要一个 H.264 解析器的时候，AI 会非常勤快地从零给我写一个。它不知道我的 base 模块里有一个经过生产验证的 h264_frame_parser，不知道 record_play 模块里还有一份，甚至不知道 rtsp_server 里还有第三份独立实现。
同一个能力，在我自己的代码库里就有三份重复实现。AI 要来了，大概率会写第四份。
这不是夸张。repo-scan 的交叉审阅报告里有一张"能力重叠地图"，看完以后我自己都吓了一跳：
| 能力域 | 重复模块 | 建议 |
|---|---|---|
| H.264 NAL 解析 | base / record_play / rtsp_server（3份独立实现） | 统一到 base |
| FAAC 音频编码 | base_codec / base_encoder / record_play（3份） | 统一到 base_codec |
| x264 视频编码 | base_codec / base_encoder（2份） | 统一到 base_codec |
| YUV 色彩转换 | base_codec / base_encoder（2份） | 统一到 base_codec |
| 位流读写 | base（3套！）/ mp4_parser | 统一到 base/bit_stream.h |
| 缓冲区管理 | base（2套命名空间 base:: vs hbase::） | 合并为一套 |
| Base64 编解码 | rtsp_server（2套实现） | 统一为1套 |
七个能力域，全都有重复。其中 H.264 解析和 FAAC 编码各有三份独立实现，位流读写甚至有四份。
实际报告里的数字更夸张——base 基础库在整个代码库里被复制粘贴了 30+ 份 ：
这就是10年代码的真相：写的时候每次都觉得"快速搞定最重要"，结果同一个东西在不同模块里被独立实现了好几遍。 我自己都记不清哪些能力已经有了，何况 AI？
坦白说，这个问题在没有 AI 的年代还能忍——大不了多几份重复代码，能跑就行。但到了 AI 编程时代，问题被放大了：
你让 Claude Code 帮忙写一个新的流媒体服务，它会老老实实从零实现 H.264 解析、FAAC 编码、YUV 转换——把你已经写好并验证过的东西再写一遍。
不是因为 AI 笨，是因为它根本不知道你有这些东西。新项目的目录是空的，AI 的上下文窗口里看不到你其他项目里的积累。
这不只是我一个人的问题。整个行业都在面对"AI 从零写"带来的后果。
最近两条新闻放在一起看，特别有意思：
第一条：1.9万行 Claude 写的代码直接进入了 Node.js 核心库，社区炸锅。有人呼吁"封杀 AI 代码"，有人说"只要通过测试就行"，争论到现在没有定论。
第二条：有人统计了 Claude Code 的输出去向——90% 流向了 GitHub 上不到 2 颗星的仓库。
两条新闻加在一起，画面就很清楚了：AI 在疯狂生产代码，但这些代码大部分没人用、没人维护、质量存疑。
开源维护者们已经开始集体掀桌。InfoQ 的报道说，低质量的 AI 生成 PR 正在淹没开源项目，维护者的审核负担暴增，有些项目干脆在 Contributing 指南里加了一句"禁止 AI 生成的 PR"。
与此同时，Cursor 在用实时强化学习改进 Composer 的代码生成质量，Claude Code 在优化上下文理解能力，所有 AI 编码工具都在卷"怎么让 AI 写出更好的代码"。
作为程序员，我觉得除了期待AI写出更好的代码之外，我们还需要认识到一点：当前的AI，并不认识你已经有的东西。它不是写得不好，是根本不知道你有现成的、经过验证的方案。所以每次都从零来。
AI 编程时代真正值钱的不是"会用 AI 写代码"——这个门槛正在快速归零。谁都会用 Claude Code 了，谁都能让 Cursor 帮忙补代码了。
真正值钱的，是你那些经过了生产环境验证、踩过坑、修过 bug、在真实项目里跑了好几年的成熟模块。
拿我的 base 模块来说，被23个其他模块依赖。它的线程模型、缓冲池、H.264 解析器，在生产环境里跑了多少年我自己都记不清了。早年做直播平台的时候反复锤炼过，各种边界条件都覆盖了。
再比如 base_codec，封装了 FFmpeg/x264/FDK-AAC 的编解码能力，对外提供统一接口，隐藏了底层三套库的实现差异和版本兼容问题。这套东西 AI 从零写出来当然可以——但它不知道我在 FFmpeg 从 4.x 升到 7.x 的过程中踩了哪些 API 变更的坑，不知道某个旧版解码器在 Android 10 上有个诡异的崩溃要绕。
这就是"10年代码"的真正价值：不是代码本身有多精妙，而是代码背后沉淀的工程决策。
举个例子：
base_codec里有个参数crf_val=25，声明类型是bool——但实际当int传。历史遗留的类型 bug。AI 从零写编码封装当然不会犯这个蠢，但它也不会知道，在某些场景下我故意绕过了 CRF 配置、直接走恒定码率，因为特定硬件解码器对 CRF 模式的兼容性有坑。
成熟模块 = 经过验证的工程决策 + 已经踩过的坑 + 生产环境的适配经验。
AI 能写出功能等价的代码，但写不出这些。而这些东西，恰恰是工程中最贵的部分。
那怎么办？
回到开头那个 HN 热帖——大家在手写 CLAUDE.md，告诉 AI"我的项目是什么结构"。方向是对的，但对于有10年积累的人来说，手写配置文件描述几百个源文件、几十个模块？不现实。
我仔细想了一下，应该需要有一个工具，能做这么几件事：
整个思路就是：AI 不从零开始写，而是从我已有的八十分开始，只补最后20%的胶水和定制逻辑。
经过一段时间的思考和设计，在 AI 协助下，我目前已经完成了初版。这个工具叫 古法熔炉（GufaForge）——名字的意思是：善待你的"古法编程"资产，让它们在 AI 时代重新发光。
界面如下。首先，把我的古法编程模块导入：
指定模块目录，选择 AI 配置（支持 DeepSeek、Claude、Codex 等十几种后端），点"开始扫描"。
工具会递归扫描文件，先做规则分析（文件结构、头文件依赖、编译宏），再调 AI 做增强分析（功能语义、接口抽象、质量评估）。扫描完成后，这些模块连同能力描述一起进入模块库。
然后在"项目工坊"里新建项目，描述一下需求，系统自动从模块库匹配、搜索 GitHub 补缺、胶水装配、生成工程文件：
五步走完，输出的不是一堆 AI 从零写的代码，而是一个以你的成熟模块为基座的工程项目——带着 CLAUDE.md，带着模块依赖关系，带着 AI 能理解的上下文。然后一键交给 Claude Code 或 Cursor，让 AI 从八十分开始补剩下的部分。
这篇我只讲了"为什么你的积累值钱"和"思路是什么"。下一篇我会完整演示整个流程：
如果你也有一堆写了好多年的"老代码"，不知道在 AI 时代怎么让它们发挥价值——关注我，下篇带你看完整方案。
CSS（层叠样式表，Cascading Style Sheets）用于描述 HTML 或 XML 文档的样式。通过选择器和声明组成的规则控制网页元素的呈现。
选择器 {
属性名: 属性值;
}
| 方式 | 写法示例 | 使用场景 |
|---|---|---|
| 行内样式 | <div style="color: red;"> |
单个元素临时样式 |
| 内部样式表 | <style> div { color: red; } </style> |
单页面内样式 |
| 外部样式表 | <link rel="stylesheet" href="style.css"> |
多页面复用，推荐 |
/* 这是注释 */
| 选择器 | 作用 | 特点 | 使用频率 | 示例 |
|---|---|---|---|---|
| 标签选择器 | 选中所有同名标签 | 无法差异化 | 较高 | div {} |
| 类选择器 | 选中指定 class | 灵活，可多类名 | 最高 | .nav {} |
| id 选择器 | 选中唯一 id | 唯一性，配合 JS | 较少 | #logo {} |
| 通配符选择器 | 选中所有元素 | 权重最低，影响范围大 | 特殊场景 | * {} |
类选择器示例：
<div class="box red">内容</div>
一个标签可以有多个类名，用空格分隔：class="box red"（公共样式 + 独立样式）。
通配符常用于清除内外边距：
* {
margin: 0;
padding: 0;
}
body {
font-family: "Microsoft YaHei", Arial, sans-serif; /* 字体系列 */
font-size: 16px; /* 字体大小 */
font-weight: 700; /* 粗细 100~900 */
font-style: italic; /* 斜体 */
}
复合属性（顺序固定）：
div {
font: italic 700 16px/1.5 "Microsoft YaHei";
}
必须同时保留
font-size和font-family，否则无效。
p {
color: #ff0000; /* 颜色（十六进制最常用） */
text-align: center; /* 水平对齐：left/center/right */
text-decoration: none; /* 下划线、删除线等，a 标签常用 none */
text-indent: 2em; /* 首行缩进，em 相对当前文字大小 */
line-height: 26px; /* 行高，单行文字垂直居中可设 line-height = 容器 height */
}
| 选择器 | 示例 | 说明 |
|---|---|---|
| 后代选择器 | ul li {} |
空格，选中所有后代 |
| 子选择器 | div > p {} |
>，只选直接子元素 |
| 并集选择器 | div, .nav {} |
逗号，同时选中多个 |
| 链接伪类 | a:hover {} |
LVHA 顺序：:link :visited :hover :active
|
:focus 伪类 |
input:focus {} |
获得焦点的元素 |
常用链接写法：
a {
color: #333;
text-decoration: none;
}
a:hover {
color: #c81623;
}
| 类型 | 特点 | 常见标签 |
|---|---|---|
| 块级元素 | 独占一行，可设宽高，宽默认100% |
div, p, h1~h6, ul
|
| 行内元素 | 一行多个，不能设宽高，宽高由内容撑开 |
span, a, em, strong
|
| 行内块元素 | 一行多个，可设宽高，有间隙 |
img, input, td
|
显示模式转换：
display: block; /* 转块级 */
display: inline; /* 转行内 */
display: inline-block; /* 转行内块 */
注意：行内元素的上下
margin无效，上下padding视觉上有效但不会增加元素实际占据的高度（仍由line-height决定）。尽量只给行内元素设置左右内外边距。
div {
background-color: #f0f0f0;
background-image: url(images/bg.jpg);
background-repeat: no-repeat; /* 不平铺，可选 repeat-x/repeat-y */
background-position: center top; /* 方位词或像素，如 10px 20px */
background-attachment: fixed; /* 背景固定 */
}
复合写法（推荐顺序：color image repeat attachment position）：
background: #fff url(bg.png) no-repeat fixed center;
背景半透明（CSS3，内容不透明）：
background: rgba(0, 0, 0, 0.3); /* 最后一个数 0~1，可写 .3 */
层叠性：相同选择器设置相同样式，后写的覆盖先写的（就近原则）。
继承性：子元素继承父元素的某些样式（color、font-size、line-height 等）。
line-height 无单位写法（如 1.5）子元素会按自己的 font-size 重新计算；带单位（如 1.5em）则会先计算父元素行高再继承，容易产生意外，推荐无单位写法。优先级：
| 选择器 | 权重（四位数） |
|---|---|
继承或 *
|
0,0,0,0 |
| 标签选择器 / 伪元素 | 0,0,0,1 |
| 类选择器 / 伪类 / 属性选择器 | 0,0,1,0 |
| id 选择器 | 0,1,0,0 |
行内样式 style=""
|
1,0,0,0 |
!important |
无穷大 |
0,0,1,1。content（内容） + padding（内边距） + border（边框） + margin（外边距）
border
border: 1px solid red;
border-top: 2px dashed blue;
border-collapse: collapse; /* 表格细线边框 */
padding
| 值的个数 | 含义 |
|---|---|
padding: 5px |
上下左右均为 5px |
padding: 5px 10px |
上下 5px，左右 10px |
padding: 5px 10px 20px |
上 5px，左右 10px，下 20px |
padding: 5px 10px 20px 30px |
上右下左（顺时针） |
如果盒子已有宽高，
padding/border会撑大盒子。解决方案：
- 手动减去撑大的尺寸。
- 使用
box-sizing: border-box;（推荐）。
margin
语法同 padding。
块级盒子水平居中：margin: 0 auto;（需设置宽度）。
margin-bottom 和 margin-top 会合并，取较大值。解决方法（任选一种）：
border 或 padding。overflow: hidden。display: flow-root（现代方法，不产生副作用）。flex 或 grid 布局（推荐）。* {
margin: 0;
padding: 0;
box-sizing: border-box; /* 可选，全局切换盒子模型 */
}
border-radius
div {
border-radius: 10px; /* 四个角一致 */
border-radius: 10px 20px 30px 40px; /* 左上 右上 右下 左下 */
border-radius: 50%; /* 圆形（宽高相等）或椭圆（宽高不等） */
}
box-shadow
box-shadow: h-shadow v-shadow blur spread color inset;
示例：
div:hover {
box-shadow: 10px 10px 10px -4px rgba(0,0,0,0.3);
}
text-shadow
text-shadow: 2px 2px 2px gray;
传统布局方法，新项目推荐使用 Flex 或 Grid。
float: left; /* 或 right, none */
原因：子元素浮动后，父元素高度为 0，影响后续布局。
在浮动子元素末尾添加空块级标签：<div style="clear: both;"></div>（不推荐，增加冗余标签）。
overflow: hidden
.father {
overflow: hidden;
}
.clearfix::after {
content: "";
display: block;
height: 0;
clear: both;
visibility: hidden;
}
.clearfix::before,
.clearfix::after {
content: "";
display: table;
}
.clearfix::after {
clear: both;
}
现代更简单的方式：父元素设置
display: flow-root;（无副作用，兼容性良好）。
position 值 |
说明 | 是否脱标 |
|---|---|---|
static |
默认，无偏移 | 否 |
relative |
相对自身原位置移动 | 否（占位） |
absolute |
相对最近有定位的父级 | 是 |
fixed |
相对浏览器窗口 | 是 |
sticky |
滚动到阈值后固定 | 混合 |
边偏移：top, bottom, left, right（像素或百分比）。
子元素 absolute，父元素 relative（父占位，子自由移动）。
.box {
position: absolute;
left: 50%;
margin-left: -自身宽度的一半px;
}
z-index
position 不为 static）有效。auto（0）。| 方法 | 是否占位 | 适用场景 |
|---|---|---|
display: none; |
不占位 | 常用，搭配 JS 做特效 |
visibility: hidden; |
占位 | 需要保留空间时 |
overflow: hidden; |
不占位 | 隐藏溢出部分，也可做清除浮动 |
opacity: 0; |
占位 | 透明，仍可响应事件（配合 pointer-events） |
将多个小图标合成一张图，通过 background-position 移动显示。
步骤：
.icon {
width: 20px;
height: 20px;
background-image: url(sprites.png);
background-repeat: no-repeat;
background-position: -40px -20px;
}
本质是字体，可像文字一样改变颜色、大小。
通用引入模板：
@font-face {
font-family: 'icomoon';
src: url('fonts/icomoon.woff2') format('woff2'),
url('fonts/icomoon.woff') format('woff'),
url('fonts/icomoon.ttf') format('truetype');
font-weight: normal;
font-style: normal;
}
.icon {
font-family: 'icomoon';
font-size: 16px;
}
推荐使用
iconfont.cn：www.iconfont.cn/
icomoon.io：icomoon.io/
cursor
cursor: pointer; /* 小手 */
cursor: move; /* 移动十字 */
cursor: not-allowed; /* 禁止 */
input, textarea {
outline: none;
}
textarea {
resize: none; /* 禁止拖拽改变大小 */
}
vertical-align
baseline（基线对齐），导致图片底部有空隙。vertical-align: middle / top / bottom，或 display: block。img {
vertical-align: middle;
}
.ellipsis {
white-space: nowrap;
overflow: hidden;
text-overflow: ellipsis;
}
.multiline-ellipsis {
display: -webkit-box;
-webkit-line-clamp: 2;
-webkit-box-orient: vertical;
overflow: hidden;
}
.triangle {
width: 0;
height: 0;
border: 50px solid transparent;
border-top-color: red;
}
| 选择符 | 说明 | 权重 |
|---|---|---|
E[att] |
有 att 属性的 E | 0,0,1,0 |
E[att="val"] |
att 属性值等于 val | 同上 |
E[att^="val"] |
att 属性值以 val 开头 | 同上 |
E[att$="val"] |
att 属性值以 val 结尾 | 同上 |
E[att*="val"] |
att 属性值包含 val | 同上 |
| 选择符 | 说明 | 示例 |
|---|---|---|
E:first-child |
父元素中第一个孩子且为 E | li:first-child |
E:last-child |
父元素中最后一个孩子且为 E | |
E:nth-child(n) |
父元素中第 n 个孩子且为 E（n 可为数字、odd、even、公式） | |
E:first-of-type |
父元素中第一个该类型的 E | |
E:nth-of-type(n) |
父元素中第 n 个该类型的 E |
区别：
nth-child先找第 n 个孩子，再检查是否匹配 E；nth-of-type先过滤出所有 E，再取第 n 个。 例如：div span:nth-child(1)，如果第一个子元素不是<span>，则选不中。
示例：
<ul>
<li>1</li>
<li>2</li>
<li>3</li>
</ul>
li:nth-child(2) { color: red; } /* 选中第二个 li */
li:nth-of-type(2) { color: blue; } /* 同样选中第二个 li，但如果中间有其他类型，结果可能不同 */
| 选择符 | 说明 | 权重 |
|---|---|---|
::before |
在元素内容最前面插入内容 | 0,0,0,1 |
::after |
在元素内容最后面插入内容 | 同上 |
div::before {
content: "前缀";
display: inline-block; /* 默认是行内元素，可改块级 */
}
必须设置
content属性，否则伪元素不生效。
box-sizingbox-sizing: content-box; /* 默认，宽高只包含 content */
box-sizing: border-box; /* 宽高包含 padding 和 border（推荐） */
filter
img {
filter: blur(5px); /* 模糊，单位 px */
}
calc() 函数width: calc(100% - 80px); /* 运算符两侧必须有空格 */
transition
div {
width: 100px;
transition: all 0.5s ease 0s; /* 属性 时长 运动曲线 延迟 */
}
div:hover {
width: 200px;
}
运动曲线：ease（默认）、linear、ease-in、ease-out、steps()（逐帧）。
animation
@keyframes move {
0% { transform: translateX(0); }
100% { transform: translateX(100px); }
}
div {
animation: move 2s linear infinite alternate;
}
常用属性：
| 属性 | 描述 |
|---|---|
animation-name |
关键帧名称 |
animation-duration |
持续时间 |
animation-timing-function |
速度曲线（含 steps()） |
animation-iteration-count |
播放次数（infinite 无限） |
animation-direction |
是否反向（alternate） |
animation-fill-mode |
结束状态（forwards 保持） |
animation-play-state |
暂停（paused） |
性能优化：对动画属性使用
will-change: transform;可提升流畅度。
transform
transform: translate(50px, 50px); /* 位移，百分比相对自身 */
transform: rotate(45deg); /* 旋转，正值顺时针 */
transform: scale(1.5); /* 缩放，1 为原大小 */
transform-origin: left top; /* 变换中心点 */
.father {
perspective: 500px; /* 透视，给父元素 */
transform-style: preserve-3d; /* 子元素开启 3D 空间 */
}
.child {
transform: translateZ(100px) rotateY(45deg);
}
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
| 属性 | 说明 |
|---|---|
width |
布局视口宽度，常用 device-width
|
initial-scale |
初始缩放比，通常 1.0 |
maximum-scale |
最大缩放比 |
user-scalable |
是否允许用户缩放（yes/no，但部分浏览器已忽略，建议用 maximum-scale 限制） |
/* 背景图方式 */
background-image: url(icon@2x.png);
background-size: 20px 20px;
/* 或使用 image-set */
background-image: -webkit-image-set(url(icon.png) 1x, url(icon@2x.png) 2x);
/* 或使用 img 的 srcset */
<img src="icon.png" srcset="icon@2x.png 2x" alt="">
推荐使用
normalize.css：necolas.github.io/normalize.c…
常见重置样式：
/* 去除移动端点击高亮 */
-webkit-tap-highlight-color: transparent;
/* 移除默认外观（如按钮圆角） */
-webkit-appearance: none;
/* 禁止长按菜单 */
img, a {
-webkit-touch-callout: none;
}
.container {
display: flex; /* 或 inline-flex */
flex-direction: row; /* 主轴方向：row | column */
justify-content: center; /* 主轴对齐：flex-start | center | space-between | space-around */
align-items: center; /* 交叉轴对齐：stretch | center | flex-start | flex-end */
flex-wrap: wrap; /* 换行 */
}
.item {
flex: 1; /* 子项占据剩余空间比例 */
order: 2; /* 排序，数值越小越靠前 */
}
推荐：使用 Flex 替代浮动做一维布局（水平或垂直排列）。
.container {
display: grid;
grid-template-columns: 1fr 1fr 1fr; /* 三列等分 */
grid-template-rows: auto 200px;
gap: 20px; /* 行列间距 */
}
.item {
grid-column: span 2; /* 跨越两列 */
}
适用场景：复杂网格布局，如卡片墙、相册、仪表盘。
@media (min-width: 768px) and (max-width: 1024px) {
body {
font-size: 14px;
}
}
max-width: 767px
768px - 1024px
min-width: 1025px
font-size。<script src="https://cdn.jsdelivr.net/npm/flexible.js"></script>
1vw = 视口宽度的 1%，1vh = 视口高度的 1%。.box {
width: 50vw; /* 屏幕宽度一半 */
height: 30vh; /* 屏幕高度 30% */
}
:root {
--primary-color: #3498db;
--spacing: 1rem;
}
button {
background-color: var(--primary-color);
padding: var(--spacing);
}
document.documentElement.style.setProperty('--primary-color', '#e74c3c');
优势：主题切换、代码复用、易于维护。
| 前缀 | 浏览器 |
|---|---|
-webkit- |
Chrome, Safari |
-moz- |
Firefox |
-ms- |
IE |
-o- |
Opera |
使用建议：借助 Autoprefixer 工具自动添加，手写时只写标准属性。
* 选择器（影响渲染性能）。transform 和 opacity（不触发重排）。will-change: transform;。| 坑点 | 解决方案 |
|---|---|
| 外边距塌陷 | 父元素加 overflow: hidden 或 display: flow-root
|
| 图片底部空白间隙 |
vertical-align: middle 或 display: block
|
| 浮动父元素高度塌陷 | 使用 clearfix 或 display: flow-root
|
| 行内元素上下边距无效 | 改用 display: inline-block 或块级 |
nth-child 与预期不符 |
确认是否选错孩子类型，改用 nth-of-type
|
| 绝对定位盒子没有参照物 | 给父元素加 position: relative
|
| 过渡/动画未生效 | 检查属性是否可动画（如 display: none 不能过渡） |
| 移动端点击高亮 | 设置 -webkit-tap-highlight-color: transparent
|
| 1px 边框在高清屏变粗 | 使用 transform: scale(0.5) 或 border-image
|
Pretext 核心是完全绕过 DOM，通过 “两阶段计算” 实现极速文本测量与换行。
Pretext 把 “慢操作” 和 “快操作” 彻底分离：
核心：用 Canvas 测宽 + 分词缓存
Intl.Segmenter 按 “语义单元” 拆分（英文单词、中文单字、emoji、组合字符）canvas.measureText() 测每个单元的精确宽度（不触发 DOM 重排）prepared 句柄核心：纯数学模拟浏览器换行
prepared 句柄 + 容器宽度 + 行高white-space: normal 换行规则getBoundingClientRect、不触发 Reflowjavascript
运行
import { prepare, layout } from '@chenglou/pretext'
// 1. 冷路径：一次性准备（文本/字体变了才重做）
const prepared = prepare(
'Pretext 是前端高性能文本布局库，完全绕过 DOM，两阶段计算。',
'16px Inter, sans-serif' // 字体样式（同 CSS font 简写）
)
// 2. 热路径：任意宽度、任意次数计算（极速）
const result1 = layout(prepared, 300, 24) // 宽300px，行高24px
console.log('300px宽：', result1.height, 'px，', result1.lineCount, '行')
const result2 = layout(prepared, 500, 24) // 宽500px
console.log('500px宽：', result2.height, 'px，', result2.lineCount, '行')
javascript
运行
const { lines } = layout(prepared, 350, 24)
// lines 数组：每一行的文本片段
lines.forEach((line, i) => {
console.log(`第${i+1}行：`, line.text)
})
javascript
运行
function update() {
const containerWidth = document.getElementById('text').clientWidth
const { height } = layout(prepared, containerWidth, 24)
document.getElementById('text').style.height = `${height}px`
}
// 窗口变化时，纯计算更新，无 DOM 测量
window.addEventListener('resize', update)
update()
表格
| 方式 | 原理 | 性能 | 重排 | 跨浏览器 |
|---|---|---|---|---|
| Pretext | Canvas 缓存 + 纯计算 | 0.09ms | ❌ 无 | ✅ 一致 |
DOM + getBoundingClientRect
|
渲染 → 测量 | 0.5–2ms | ✅ 有 | ❌ 差异大 |
一句话总结：Pretext = 一次 Canvas 测量 + 无限次纯数学换行，把文本布局从 DOM 瓶颈中解放出来。
Chrome 插件（扩展程序）可以为浏览器增加新功能，修改网页行为，与用户交互。本教程将带你从零开始，掌握 Chrome 插件开发的全部核心知识，最终能够开发、调试并发布自己的插件。
Chrome 插件概述
开发环境准备
Manifest V3 配置文件
第一个插件：Hello World
插件核心组件详解
消息传递机制
数据存储
权限与 API
调试与测试
打包与发布
高级主题
最佳实践与注意事项
结语
Chrome 插件（扩展程序）是运行在浏览器中的小程序，可以增强浏览器功能或与当前浏览的页面交互。插件通常由 HTML、CSS、JavaScript 以及一个清单文件（manifest.json）组成。每个插件都有一个唯一的标识（扩展 ID），并可申请特定权限来访问 Chrome API 或用户数据。
插件的常见用途：
从 2022 年起，Chrome 要求所有插件使用 Manifest V3，新插件必须以 V3 开发。
开发 Chrome 插件无需复杂的环境，只需：
推荐步骤：
在本地创建一个文件夹，作为插件项目根目录。
编写代码。
在 Chrome 中加载未打包的扩展程序进行测试：
chrome://extensions/
每次修改代码后，在扩展程序页面点击刷新按钮（🔄）即可重新加载插件。
manifest.json 是插件的“身份证”，必须放在根目录。一个最基本的 V3 清单文件如下：
{
"manifest_version": 3,
"name": "我的第一个插件",
"version": "1.0.0",
"description": "一个简单的Chrome插件示例",
"icons": {
"16": "icons/icon16.png",
"48": "icons/icon48.png",
"128": "icons/icon128.png"
},
"action": {
"default_popup": "popup.html",
"default_icon": {
"16": "icons/icon16.png",
"48": "icons/icon48.png",
"128": "icons/icon128.png"
}
},
"background": {
"service_worker": "background.js"
},
"permissions": [
"storage",
"activeTab"
],
"host_permissions": [
"<all_urls>"
],
"content_scripts": [
{
"matches": ["<all_urls>"],
"js": ["content.js"],
"css": ["content.css"]
}
],
"options_ui": {
"page": "options.html",
"open_in_tab": false
}
}
关键字段说明：
manifest_version：必须为 3。name、version、description：插件基本信息。icons：插件图标，推荐提供多种尺寸。action：定义浏览器工具栏上的按钮（V3 中统一使用 action，不再区分 browser_action 和 page_action）。default_popup 指定点击按钮后弹出的 HTML 页面。background：后台脚本，V3 中使用 Service Worker，不能是持久化页面。service_worker 指定脚本文件。permissions：需要声明的权限，如 storage（存储）、activeTab（当前标签页）等。host_permissions：需要访问的主机权限，如 "<all_urls>" 表示所有网址。content_scripts：注入到网页中的脚本，会在页面加载时运行。matches 指定匹配的 URL 模式。options_ui：选项页面，用户可在扩展管理页面点击“选项”打开。我们创建一个最简单的插件：点击工具栏图标，弹出一个显示“Hello World”的弹出窗口。
新建文件夹 hello-extension，在其中创建以下文件：
manifest.jsonpopup.htmlpopup.js（可选）icon.png（任意图片，作为图标）{
"manifest_version": 3,
"name": "Hello World 插件",
"version": "1.0",
"description": "第一个插件",
"icons": {
"16": "icon.png",
"48": "icon.png",
"128": "icon.png"
},
"action": {
"default_popup": "popup.html",
"default_icon": "icon.png"
}
}
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<style>
body { width: 200px; height: 100px; display: flex; justify-content: center; align-items: center; font-family: sans-serif; }
h1 { color: #4CAF50; }
</style>
</head>
<body>
<h1>Hello World!</h1>
<script src="popup.js"></script>
</body>
</html>
console.log('Popup 已打开');
chrome://extensions/
hello-extension 文件夹恭喜！你已经完成了第一个 Chrome 插件。
弹出页面是一个简单的 HTML 页面，在用户点击工具栏图标时显示。它的生命周期很短：每次点击都会重新加载，关闭即销毁。因此适合做简单的交互，不适合保存状态。如果需要在弹出页面中存储数据，可以结合 chrome.storage 或 localStorage（但注意 localStorage 在弹出页面中与普通网页一样是隔离的）。
弹出页面可以访问部分 Chrome API，但权限取决于插件的 permissions。
示例：在弹出页面中显示当前标签页的 URL。
<!-- popup.html -->
<body>
<div id="url">当前页面URL：</div>
<script src="popup.js"></script>
</body>
// popup.js
chrome.tabs.query({ active: true, currentWindow: true }, (tabs) => {
document.getElementById('url').innerText += tabs[0].url;
});
注意：需要 activeTab 或 tabs 权限。
背景脚本是插件的“大脑”，用于监听浏览器事件、处理长时间运行的任务。V3 中，它是 Service Worker，在需要时启动，空闲时终止，因此不能使用全局变量持久保存状态。必须将数据存储到 chrome.storage 或 IndexedDB 中。
常用场景：
示例：监听插件安装事件。
// background.js
chrome.runtime.onInstalled.addListener((details) => {
if (details.reason === 'install') {
console.log('插件已安装');
// 初始化存储等操作
} else if (details.reason === 'update') {
console.log('插件已更新');
}
});
清单文件必须声明 background.service_worker。
内容脚本注入到网页中，可以访问并修改 DOM，但无法直接使用大部分 Chrome API（如 chrome.tabs）。它们运行在独立的作用域，与页面脚本隔离，但可以通过 DOM 与页面脚本通信（通过 window.postMessage）或通过消息传递与后台脚本通信。
示例：在页面中所有链接后添加“🔗”符号。
// content.js
const links = document.querySelectorAll('a');
links.forEach(link => {
link.insertAdjacentText('afterend', ' 🔗');
});
清单文件中需配置 content_scripts，或在运行时通过 chrome.scripting.executeScript 动态注入。
为用户提供插件的设置界面，用户可在扩展管理页面点击“选项”按钮打开。选项页面可以是一个完整的 HTML 页面，通常用于保存用户偏好设置。
示例：一个简单的选项页面，允许用户设置背景颜色。
<!-- options.html -->
<body>
<label>背景颜色：<input type="color" id="bgColor"></label>
<button id="save">保存</button>
<script src="options.js"></script>
</body>
// options.js
document.getElementById('save').addEventListener('click', () => {
const color = document.getElementById('bgColor').value;
chrome.storage.sync.set({ bgColor: color }, () => {
console.log('已保存');
});
});
// 加载已保存的颜色
chrome.storage.sync.get('bgColor', (data) => {
if (data.bgColor) document.getElementById('bgColor').value = data.bgColor;
});
清单中需包含 options_ui。
插件可以添加自定义右键菜单项。需要在后台脚本中调用 chrome.contextMenus.create 创建菜单，并监听 chrome.contextMenus.onClicked 事件。
权限：需要 contextMenus 权限。
示例：添加右键菜单“查看链接文本”，点击后弹出提示。
// background.js
chrome.runtime.onInstalled.addListener(() => {
chrome.contextMenus.create({
id: "show-link-text",
title: "查看链接文本",
contexts: ["link"] // 仅在链接上显示
});
});
chrome.contextMenus.onClicked.addListener((info, tab) => {
if (info.menuItemId === "show-link-text") {
const linkText = info.linkText;
chrome.scripting.executeScript({
target: { tabId: tab.id },
func: (text) => alert(`链接文本：${text}`),
args: [linkText]
});
}
});
注意：右键菜单在 V3 中需要 host_permissions 来执行脚本，或者使用 activeTab 权限（用户点击插件图标时授权）。
插件可以发送系统通知，需要使用 notifications 权限。
示例：
chrome.notifications.create({
type: "basic",
iconUrl: "icon.png",
title: "提醒",
message: "这是一条通知"
}, (notificationId) => {
console.log("通知已创建，ID：" + notificationId);
});
在 Manifest V3 中，两者统一为 action。但概念上：
action 动态设置图标或禁用状态来实现类似效果。由于各组件（背景、内容脚本、弹出页面、选项页面）运行在不同环境，需要通过消息传递进行通信。
使用 chrome.runtime.sendMessage 发送消息，chrome.runtime.onMessage 接收。
示例：内容脚本向后台发送消息，后台处理后返回结果。
content.js
chrome.runtime.sendMessage({ greeting: "hello" }, (response) => {
console.log("后台回复：" + response.reply);
});
background.js
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
if (message.greeting === "hello") {
sendResponse({ reply: "world" });
}
return true; // 异步响应时需要返回 true
});
同上，sendMessage 的第二个参数是回调函数，接收 sendResponse 的结果。注意若回调是异步的，需要在监听器中返回 true，否则 sendResponse 会失效。
使用 chrome.runtime.connect 建立长连接，通过 port.postMessage 和 port.onMessage 通信。
示例：后台与内容脚本建立长连接。
background.js
chrome.tabs.onUpdated.addListener((tabId, changeInfo, tab) => {
if (changeInfo.status === 'complete') {
const port = chrome.tabs.connect(tabId, { name: "my-connection" });
port.postMessage({ data: "页面加载完成" });
port.onMessage.addListener((msg) => {
console.log("收到来自页面的消息：", msg);
});
}
});
content.js
chrome.runtime.onConnect.addListener((port) => {
if (port.name === "my-connection") {
port.onMessage.addListener((msg) => {
console.log("收到来自后台的消息：", msg);
port.postMessage({ reply: "收到" });
});
}
});
推荐使用 chrome.storage API 存储数据，它是异步的，且与浏览器同步（如果使用 sync 存储，会在登录 Chrome 的用户间同步）。数据大小限制：sync 约 100KB，local 约 5MB（可申请更多）。
local：仅存储在本地，数据量大，不跨设备同步。sync：跨设备同步，但容量小，适合存储用户偏好。// 存储数据
chrome.storage.sync.set({ key: "value" }, () => {
console.log("已保存");
});
// 读取数据
chrome.storage.sync.get(["key"], (result) => {
console.log("读取到的值：" + result.key);
});
// 移除数据
chrome.storage.sync.remove("key", () => {
console.log("已移除");
});
// 监听存储变化
chrome.storage.onChanged.addListener((changes, areaName) => {
console.log("存储变化：", changes, areaName);
});
activeTab：临时获取当前活动标签页的访问权限，用户点击插件按钮时自动授予，适合无需复杂权限的场景。tabs：访问标签页的完整信息（URL、标题等），并可操作标签页（创建、更新、关闭）。storage：使用 chrome.storage。cookies：操作 cookies。webRequest：拦截和修改网络请求（V3 中需使用 declarativeNetRequest）。notifications：显示桌面通知。contextMenus：添加右键菜单。bookmarks、history 等。V3 中，部分权限可在运行时通过 chrome.permissions.request 请求。例如：
chrome.permissions.request({
permissions: ["cookies"],
origins: ["*://*.example.com/*"]
}, (granted) => {
if (granted) console.log("权限已授予");
});
同时可以检查权限、移除权限等。
chrome://extensions/ 中点击插件卡片下的“背景页”链接，可以打开 DevTools 调试 Service Worker。chrome://extensions/ 页面，如果插件有错误，卡片上会有“错误”按钮，点击查看详情。准备图标：必须提供至少 128x128 的图标，建议提供 16、48、128 三种尺寸。
添加商店描述：准备详细说明、截图（至少 1 张）、宣传图（可选）。
创建开发者账户：登录 Chrome Web Store 开发者控制台，支付一次性注册费（约 5 美元）。
打包插件：
chrome://extensions/ 中，点击“打包扩展程序”，选择项目根目录，会生成 .crx 文件和私钥（.pem）。私钥务必保存好，用于后续更新。上传：在开发者控制台点击“新增项目”，上传 .crx 或直接上传项目 zip。填写表单，提交审核。审核通常需要几小时到几天。
更新：修改 manifest.json 中的 version 号，重新打包（使用原来的私钥），在控制台上传更新。
插件可以添加自己的面板到 Chrome DevTools 中。需要声明 devtools_page 字段，并编写对应的 HTML 和 JS。
"devtools_page": "devtools.html"
devtools.html 中引入 JS，调用 chrome.devtools.panels.create 创建面板。
可以替换 Chrome 的某些内置页面，如新标签页、书签页、历史页。需要在 chrome_url_overrides 字段中声明。
"chrome_url_overrides": {
"newtab": "my-newtab.html"
}
Manifest V3 允许在扩展中使用 WebAssembly，可以提高某些计算密集型任务的性能。只需将 .wasm 文件包含在插件包中，并在 JavaScript 中加载即可。
支持多语言：创建 _locales 文件夹，下设语言子文件夹（如 en、zh_CN），内含 messages.json。在 manifest.json 中可使用 __MSG_xxx__ 引用本地化字符串。
messages.json 示例：
{
"extensionName": {
"message": "我的插件",
"description": "插件名称"
},
"extensionDescription": {
"message": "一个示例插件",
"description": "插件描述"
}
}
在 manifest 中："name": "__MSG_extensionName__"。
eval 或 innerHTML 插入未经验证的外部数据，防止 XSS 攻击。尽量使用 textContent 或 createElement。chrome.storage.sync 让设置随账号同步。onError 或检查 chrome.runtime.lastError）。chrome.runtime.getManifest() 检查清单版本，有条件地使用 API。Chrome 插件开发是一个门槛低但可以非常深入的技术。通过本教程，你已经掌握了从清单配置到各个组件、从消息传递到存储、从调试到发布的完整流程。现在，你可以开始构思自己的插件创意，并将它实现出来。
继续探索 Chrome 官方文档（developer.chrome.com/docs/extensions/），那里有更详细的 API 参考和大量示例。祝你开发顺利，创造出有用的插件！
在大数据可视化场景中，1 万～10 万条数据的图表渲染常面临 “白屏卡顿”“崩溃闪退” 等问题。传统一次性加载方案早已无法满足需求，而 SSE（Server-Sent Events）流式推送 + ECharts appendData 增量渲染 成为业界公认的最优解。本文将从底层原理到实战代码，全方位拆解这一方案，所有内容基于 W3C 标准与 ECharts 官方文档，可直接复制到生产环境。
SSE 是 HTML5 标准规范的 HTTP 长连接单向推送技术，允许服务器通过持久连接，将数据以 “数据块（Chunk）” 形式持续推送给客户端，客户端无需反复请求。
| 对比维度 | SSE | WebSocket |
|---|---|---|
| 通信方向 | 单向（服务端→客户端） | 全双工（双向） |
| 协议基础 | HTTP 协议 | 独立 WebSocket 协议 |
| 实现成本 | 极低（原生 API，几行代码） | 较高（需处理握手、协议解析） |
| 适用场景 | 图表数据、通知、日志流式输出 | 聊天、实时协作、游戏 |
| 兼容性 | 除 IE 外所有现代浏览器原生支持 | 大部分现代浏览器支持 |
结论：图表数据仅需 “服务端推送给客户端”，SSE 比 WebSocket 更轻量、更简单，无需多余的双向通信能力。
ECharts 的 setOption 是 “全量重绘” API：每次调用会重新解析所有数据、计算图表布局、渲染整个画布。当数据量 > 5000 条时，会阻塞主线程，导致页面卡顿；> 1 万条时，极易出现崩溃。
appendData 是 ECharts 4.0+ 推出的 增量渲染 API，专为大数据设计：
官方文档明确说明： “大数据量场景下，appendData 是唯一推荐的渲染方式” （出处：ECharts 大数据最佳实践）。
通过 “流式传输 + 增量渲染”，从根源解决上述问题：
底层逻辑流程图：
服务端分批读取数据（每批 500～1000 条）
→ 按 SSE 标准格式封装成数据块
→ 通过 HTTP 长连接推送给客户端
→ 客户端 EventSource 接收数据块
→ 调用 ECharts appendData 追加渲染
→ 重复上述步骤直到所有数据推送完成
→ 关闭 SSE 连接
<html lang="zh-CN">
8">
name="viewport" content="width=device-width, initial-scale=1.0">
万级数据 SSE 流式渲染
Charts -->
<script src="https://cdn.bootcdn.net/ajax/libs/echarts/5.4.3/echarts.min.js"> { margin: 0; padding: 0; box-sizing: border-box; }
body { padding: 20px; font-family: Arial, sans-serif; }
#chart-container { width: 100%; height: 600px; border: 1px solid #eee; }
#loading { margin: 10px 0; font-size: 16px; color: #333; }
.progress { color: #1890ff; font-weight: bold; }
</style>
</head>
">加载状态： class="progress">连接中...</span> -container"> 1. 初始化 ECharts 实例
const chartDom = document.getElementById('chart-container');
const myChart = echarts.init(chartDom);
const loadingEl = document.querySelector('.progress');
// 2. 初始化空图表配置（关键：必须先设置空数据）
const initOption = {
tooltip: {
trigger: 'axis',
axisPointer: { type: 'shadow' },
// 大数据优化：关闭悬浮动画
animation: false
},
legend: { data: ['随机数据'] },
grid: {
left: '3%',
right: '4%',
bottom: '3%',
containLabel: true
},
xAxis: {
type: 'category',
data: [], // 初始空数据
// 大数据优化：关闭坐标轴动画
axisLabel: { interval: 500 } // 每隔 500 个点显示一个标签，避免重叠
},
yAxis: {
type: 'value',
animation: false
},
series: [{
name: '随机数据',
type: 'line',
smooth: true,
data: [], // 初始空数据
showSymbol: false, // 关键优化：关闭数据点显示（极大提升性能）
lineStyle: { width: 1 }, // 线条变细，减少渲染压力
animation: false // 关闭系列动画
}],
animation: false // 全局关闭动画（大数据必备）
};
myChart.setOption(initOption);
// 3. 配置 SSE 连接与数据处理
const totalDataCount = 10000; // 总数据量
let loadedCount = 0; // 已加载数据量
// 创建 SSE 连接（后端接口地址）
const eventSource = new EventSource('http://localhost:3000/api/sse/echarts-data');
// 4. 监听 SSE 消息（接收服务端推送的数据块）
eventSource.onmessage = function(e) {
// 解析服务端推送的字符串数据
const response = e.data.trim();
// 数据推送完成的标识（与后端约定）
if (response === 'COMPLETE') {
loadingEl.textContent = `加载完成：${loadedCount}/${totalDataCount} 条`;
eventSource.close(); // 关闭 SSE 连接
return;
}
// 解析 JSON 数据块
const { xData, seriesData } = JSON.parse(response);
loadedCount += seriesData.length;
// 5. 增量渲染（核心：调用 appendData 而非 setOption）
myChart.appendData({
seriesIndex: 0, // 要追加数据的系列索引（对应 initOption 中的 series[0]）
data: seriesData // 追加的系列数据
});
// 追加 X 轴数据（如果 X 轴是动态的）
myChart.appendData({
xAxisIndex: 0, // 要追加数据的 X 轴索引
data: xData // 追加的 X 轴数据
});
// 更新加载进度
loadingEl.textContent = `加载中：${loadedCount}/${totalDataCount} 条`;
};
// 6. 监听 SSE 错误
eventSource.onerror = function(error) {
console.error('SSE 连接异常：', error);
loadingEl.textContent = '加载失败，请刷新重试';
eventSource.close();
};
// 7. 监听页面关闭，主动关闭 SSE 连接
window.addEventListener('beforeunload', function() {
eventSource.close();
});
</body>
</html>
// 1. 安装依赖：npm install express cors
const express = require('express');
const cors = require('cors');
const app = express();
// 2. 跨域配置（前端若与后端不同域，必须配置）
app.use(cors({
origin: '*', // 生产环境建议指定具体域名，如 'http://your-frontend-domain.com'
methods: ['GET', 'POST'],
allowedHeaders: ['Content-Type']
}));
// 3. SSE 接口：推送 1 万条数据
app.get('/api/sse/echarts-data', (req, res) => {
// 关键：设置 SSE 响应头（必须严格遵循规范）
res.setHeader('Content-Type', 'text/event-stream; charset=utf-8');
res.setHeader('Cache-Control', 'no-cache'); // 禁止缓存（避免数据重复）
res.setHeader('Connection', 'keep-alive'); // 保持连接
res.setHeader('X-Accel-Buffering', 'no'); // 禁用 Nginx 缓冲（关键！否则数据会被批量推送）
// 配置参数
const totalDataCount = 10000; // 总数据量
const batchSize = 1000; // 每批推送数据量（最优值：500～1000 条）
let currentIndex = 0; // 当前推送索引
// 4. 分批推送数据
const pushData = () => {
// 计算当前批的起始和结束索引
const start = currentIndex;
const end = Math.min(currentIndex + batchSize, totalDataCount);
// 构造当前批数据
const xData = []; // X 轴数据（这里用索引模拟）
const seriesData = []; // 系列数据（随机数模拟）
for (let i = start; i ++) {
xData.push(`点 ${i + 1}`);
seriesData.push(Math.floor(Math.random() * 1000)); // 0～999 的随机数
}
// 5. 按 SSE 标准格式发送数据（必须严格遵循）
// 格式要求：data: [JSON字符串]\n\n（双换行结尾）
const dataStr = JSON.stringify({ xData, seriesData });
res.write(`data: ${dataStr}\n\n`);
// 更新当前索引
currentIndex = end;
// 6. 所有数据推送完成，发送结束标识
if (currentIndex >= totalDataCount) {
res.write(`data: COMPLETE\n\n`); // 结束标识（与前端约定）
res.end(); // 关闭连接
return;
}
// 7. 控制推送频率（避免服务器压力过大，每 100ms 推一批）
setTimeout(pushData, 100);
};
// 开始推送第一批数据
pushData();
// 8. 监听客户端断开连接，清理资源
req.on('close', () => {
console.log('客户端断开 SSE 连接');
res.end();
});
});
// 9. 启动服务器
const port = 3000;
app.listen(port, () => {
console.log(`服务器运行在 http://localhost:${port}`);
console.log(`SSE 接口：http://localhost:${port}/api/sse/echarts-data`);
});
ECharts 万级数据渲染的核心是 “分而治之”：通过 SSE 将数据 “分块流式传输”，避免网络和解析瓶颈；通过 ECharts appendData 将渲染 “增量执行”，避免全量重绘的性能消耗。
这一方案完全基于标准技术，无需复杂的第三方库，实现简单且性能稳定，是生产环境中大数据可视化的首选方案。本文代码可直接复制运行，如需扩展到 10 万条以上数据，可结合 “采样 + 分页” 进一步优化。
开门见山，这是我开源的绣化版本bestofjs—— Best of RS!
Github: github.com/zhiyanzhaij…
官网: bestofrs.org
已上线稳定运行一个多月，目前文档、CI齐全，所以各平台做下宣传。
一个基于 Rust 的
Clean & Hexagonal Doamin Driven Design架构, 结合dioxus全栈。
Notice: 本文档所用图表均由Excalidraw绘制, 在此鸣谢。
先看项目分层：
crates/
- adapters/ # Clean Core
- app/ # Clean Core
- domain/ # Clean Core
- infra/ # Clean Core
- ui/ # User Interface
- worker/ # User Interface
本项目架构参考 axum-clean-architecture by @Thodin，并结合了 Dioxus fullstack 的工程实践。
核心依赖方向：
domain <- app(application) <- adapter <- infra(infrastructure) <- user interface
crates/domain/src）crates/domain/src
├── auth
├── error.rs
├── lib.rs
├── project
├── repo
└── snapshot
auth / project / repo / snapshot：按业务子域划分的领域模型error.rs：领域级错误语义lib.rs：领域模块导出边界Domain层承载领域语义与业务不变式，只关心领域建模，不关心业务编排与技术实现。
project 为例crates/domain/src/project
├── entity.rs (实体)
├── event.rs (领域事件)
├── mod.rs
└── value_object.rs (值对象)
crates/app/src）crates/app/src
├── app_error.rs
├── auth
├── backup
├── common
├── lib.rs
├── prelude.rs
├── project
├── repo
└── snapshot
common、app_error.rs：跨 use case 的通用业务逻辑与统一错误语义auth / backup / project / repo / snapshot：不同领域用例（use cases）模块prelude.rs：应用层常用导出Application层负责业务编排（Use Cases），通过端口抽象依赖外部能力，不直接依赖具体基础设施实现。
project 为例crates/app/src/project
├── command.rs (CQRS - read用例)
├── event_handler.rs (领域事件驱动编排)
├── impls (充血模型实现，Rich Domain Model)
├── mod.rs
├── port.rs (Hexagonal Port)
└── query.rs (查询用例)
crates/adapters/src + crates/ui/src/IO）crates/adapters/src
├── auth
├── clock.rs
├── github.rs
├── lib.rs
├── persistence
└── prelude.rs
persistence：存储适配实现auth：鉴权/授权相关适配github.rs：外部 API 适配clock.rs：时间能力适配Adapter层负责技术编排与边界转换，把 Application ports 落地为具体实现。
补充：HTTP endpoint 的实现代码位于 crates/ui/src/IO。这是“物理位置在 ui，逻辑归属在 Adapter”的工程布局。
persistence/psql 为例crates/adapters/src/persistence/psql
├── backup.rs (数据备份实现)
├── db.rs (数据库连接实现)
├── mod.rs
├── project_repo.rs (Project 仓储实现)
├── repo_repo.rs (Repo 仓储实现)
├── repo_tag_repo.rs (Tag 仓储实现)
├── runtime.rs (运行时装配)
└── snapshot_repo.rs (Snapshot 仓储实现)
crates/infra/src）crates/infra/src
├── config
├── lib.rs
└── setup.rs
config：配置模型与配置来源setup.rs：装配入口，负责初始化与依赖注入lib.rs：基础设施模块导出Infrastructure层只做系统装配与启动准备，不承载业务规则。
config 为例crates/infra/src/config
├── mod.rs (配置模块导出)
├── settings.rs (配置结构定义)
└── toml (环境配置文件目录)
Worker 与 UI 同属 User Interface，但交互对象不同：
UI 面向用户交互界面Worker 面向任务调度与后台执行crates/ui/src）crates/ui/src
├── IO
├── components
├── impls
├── js
├── lib.rs
├── main.rs
├── root
└── types
- `main.rs`：UI/Web 入口与服务启动入口（fullstack）
- `root`：页面布局与Router
- `components`：可复用 UI 组件（目前，出于KISS原则考虑，我将页面组件也放入其中，受影响于Next.js的App Router组织风格）
- `types` 前端viewmodel数据结构
- `impls / js`：前端侧实现细节
Notice：IO 目录虽物理上位于 ui，但本质逻辑为HTTP endpoint adapter的axum实现,在架构归属上属于 Adapter。
参考下图：
Dioxus v0.7.0+ 版本提供了非常便捷的#[post], #[get]等宏，这些宏在提供无缝的fullstack体验的前提下，又保证了代码整洁。
具体的Fullstack原理请参考Dioxus官方文档。
为了更优雅的SSR实现，我根据以往的前端工程经验，创建了
面向复杂ui组件的mod-like样板：
crates/ui/src/components/**/exampleComp/
├── mod.rs #组件
├── skeleton.rs #loading fallback
├── error.rs #错误fallback
├── hook.rs #私有hook
├── context.rs #私有context
├── style.css #若tailwind样式不便
├── (optional)sub-Comp/ #若有子组件，则样板递归
并封装IOCell组件收敛ssr处理逻辑。
还有最简单的纯组件样板，compName.rs, 这个没有特别点，不做展开。
crates/worker/src）crates/worker/src
└── main.rs
依赖core层功能的快捷应用，当前仅使用到snapshot领域下一个小的快照功能。略。
bestofjs.org受益良多，在写rust的时候一直想，想着想着就有个这么个点子Best Of RS出来了（PS：求个💼，请github邮箱联系~♥️）欢迎使用Best Of RS， 如果有所帮助, Star秋梨膏！Orz!!!!
在前端开发的“战场”上，我们常常会遇到一些“话痨”事件：用户疯狂点击按钮、快速输入搜索词、或者像拉面条一样不停拖动窗口大小。如果对这些高频事件来者不拒，浏览器很快就会因为处理不过来而“罢工”，导致页面卡顿甚至崩溃。
为了解决这个问题，我们需要两位“交通指挥官”：防抖（Debounce）和节流（Throttle）。
今天，我们就结合一段经典的实战代码，来看看这两位指挥官是如何维持秩序，让页面性能稳如泰山的。
首先，让我们直面你提供的这段核心代码。这不仅仅是几行 JavaScript，这是控制事件频率的“宪法”。
我们将以这个通用的 ajax 请求函数作为被管理的对象：
function ajax(content) {
console.log('ajax request', content);
}
防抖（Debounce）的核心逻辑是：“不管你怎么触发，我只在最后一次操作结束后的 N 毫秒执行。”
这就好比电梯关门：电梯门打开后，只要还有人陆续进来（触发事件），门就会一直开着，计时器重置。只有当一段时间（比如 5 秒）没人进出了，门才会真正关上（执行函数）。
让我们看看代码是如何实现这一逻辑的：
function debounce(fn, delay) {
var id; // 闭包中的自由变量，用于存储定时器ID
return function(args) {
if(id) clearTimeout(id); // 核心：如果之前有定时器，立马清除（重置计时）
var that = this;
id = setTimeout(function() {
fn.call(that, args) // 延迟执行真正的函数
}, delay);
}
}
var id 被包裹在闭包中，这意味着每次触发事件时，我们都能访问到同一个定时器变量。clearTimeout(id) 是防抖的灵魂。用户在输入框里每敲一个键，之前的计时就被打断，重新开始倒数。this 的指向：代码中特意保存了 var that = this，并在 setTimeout 中使用 fn.call(that, args)。这是为了防止定时器执行时 this 意外指向 window，确保上下文环境正确。节流（Throttle）的核心逻辑是：“不管你怎么触发，我每隔 N 毫秒只执行一次。”
这就像水龙头滴水：无论你水龙头拧得有多快多猛，水滴只能按照固定的频率一滴一滴往下落。或者想象一下机枪射击，扣住扳机不放，子弹也是按射速一颗颗射出，而不是一瞬间把弹夹全打光。
代码实现稍微复杂一点，它结合了“时间戳”和“定时器”的双重保险（混合版节流）：
function throttle(fn, delay) {
let last, // 记录上次执行的时间戳
deferTimer; // 定时器
return function(args) {
let that = this;
let _args = arguments;
let now = + new Date(); // 获取当前时间戳
// 如果上次执行过，且当前时间还没到下次执行的时间点（在冷却期内）
if(last && now < last + delay) {
clearTimeout(deferTimer);
// 设置一个定时器，确保在冷却期结束后至少执行一次（这是混合版的优势）
deferTimer = setTimeout(function() {
last = now;
fn.apply(that, _args);
}, delay);
} else {
// 第一次触发，或者已经过了冷却期，立即执行
last = now;
fn.apply(that, _args);
}
}
}
now < last + delay 用来判断是否处于“冷却时间”内。deferTimer。这意味着，如果用户一直触发事件，函数不仅会立即执行一次（else 分支），还会在停止触发后的 delay 时间后再执行一次（if 分支里的 setTimeout）。这保证了操作的开头和结尾都不会被遗漏。为了直观地展示效果，代码中设置了三个输入框，分别对应“无限制”、“防抖”和“节流”三种状态：
const inputa = document.getElementById('undebounce'); // 裸奔的输入框
const inputb = document.getElementById('debounce'); // 穿了防抖铠甲
const inputc = document.getElementById('throttle'); // 装了节流阀门
let debounceAjax = debounce(ajax, 500); // 500ms 防抖
let throttleAjax = throttle(ajax, 1000); // 1000ms 节流
// 1. 无限制：用户每敲一个字，控制台就打印一次。如果敲得快，请求会堆积。
inputa.addEventListener('keyup', function(e) {
ajax(e.target.value)
})
// 2. 防抖：用户快速输入 "Hello"，控制台只会打印一次 "Hello"。
// 只有当用户停下手超过 500ms，请求才会发送。
inputb.addEventListener('keyup', function(e) {
debounceAjax(e.target.value)
})
// 3. 节流：用户快速输入。
// 第一次按键立即打印。
// 接下来 1 秒内的按键会被忽略，或者在停止 1 秒后打印最后一次。
inputc.addEventListener('keyup', function(e) {
throttleAjax(e.target.value);
})
| 特性 | 防抖 | 节流 |
|---|---|---|
| 核心逻辑 | 最后一次说了算 | 固定频率执行 |
| 生活比喻 | 电梯关门、核弹发射按钮 | 水龙头滴水、机关枪射击 |
| 适用场景 | 搜索框输入（等用户输完再搜）、窗口 resize（等拖完再计算布局）、表单验证 | 滚动加载（scroll 事件，每隔一段距离加载一次）、按钮点击（防止重复提交）、鼠标移动（mousemove） |
| 代码特征 |
clearTimeout 是核心 |
Date.now() 或 setTimeout 周期性执行 |
一句话口诀： 如果**“等用户停下来再做”，请用防抖**； 如果**“不管用户多快，我要按节奏来”，请用节流**。
掌握这两段代码，你就掌握了前端性能优化的半壁江山！ 这篇解析是否清晰地展示了防抖与节流的区别？如果需要，我可以为你补充这两个函数的定时器版节流实现，或者整理一份面试中常见的防抖节流考点，你需要吗？
一、Vue3基础环境配置
1、安装Node.js
打开nodejs官方网站nodejs.org/
2、验证安装
node -v
npm -v
3、安装Vue CLI
npm install -g @vue/cli
4、创建Vue项目
vue create my-vue-project
5、进入项目目录并启动
cd my-vue-project
npm run serve
6、构建项目（可选）
npm run build
二、Vue3配置Bootstrap框架
1、安装Bootstrap
npm install bootstrap@latest
2、在Vue组件中引入Bootstrap
import 'bootstrap/dist/css/bootstrap.min.css';
import 'bootstrap/dist/js/bootstrap.bundle.min.js';
本章基于基础事实来讲述NameSpace的重要性
图注：所有前端请求在这里统一安检、分流，走向正确的后端服务。
在没有统一 BFF 的时代，一个前端工程师的日常，常常伴随着一些令人抓狂的场景：
"小王，我本地环境起不来，访问你的接口报跨域了，你那能开一下 CORS 吗？" "李工，麻烦问下，我要联调用户中心的 PPE 环境，请求头里要加哪个环境标来着？是
X-TT-ENV还是X-TT-PPE？" "奇怪，我明明在测试环境，为什么创建的订单会出现在线上数据库里？！"
这些问题听起来琐碎，却像慢性毒药一样，日复一日地消耗着前端团队的精力和耐心。
这些混乱现象的背后，是几个长期困扰前端的根源性问题：
a.company.com，却要调用 user.company.com 和 order.company.com 的接口。为了解决跨域，前端不得不与各种 Access-Control-Allow-Origin 配置斗智斗勇。更糟糕的是鉴权，每个前端项目都得复制粘贴一套逻辑去解析 Token、判断登录态、处理会话过期，并小心翼翼地将凭证附带在每一个发往不同域的微服务请求上。为了彻底终结这场噩梦，笔者在 BFF 中引入了两个最基础也最重要的模块：Proxy (统一代理) 和 Namespace (命名空间)。
笔者的设计思路非常明确：让前端变得绝对"无脑"。
前端工程师只需要向同域名的 BFF 发起最普通的 HTTP 请求，不关心目标服务的真实地址，不关心当前是什么环境，也不用操心如何携带 Token。剩下的所有脏活累活——鉴权、环境路由映射、协议转换、凭证注入——全部由 BFF 在后台悄无声息地完成。
图注：每个 Namespace 如同独立的办公区，拥有自己的门禁和访客规则。
同时，笔者引入了"命名空间 (Namespace)"的概念，实现了多租户隔离，并将不同的业务线（或客户）划分到独立的 Namespace 中。每个 Namespace 拥有自己独立的认证模式 (AuthMode)、独立的路由元数据 (RouteMeta) 和独立的微服务版本映射。这就像为每个团队分配了专属的、隔音的办公室，互不打扰。
在代码实现上，这套机制如同一条精密的流水线，优雅地处理着每一笔前端请求：
路由与元数据映射 (RouteMeta)：
前端发起的请求路径通常被设计为一种约定格式，例如 /proxy/:namespace/:service/:method。当这样的请求到达 BFF 的 ProxyController 时，BFF 首先会根据 :namespace 和 :service 去数据库（或 Redis 缓存）中查找 RouteMeta。这一步确保了系统只代理那些真正在 BFF 注册过的、合法的接口，有效防止了恶意扫描。同时，BFF 会从元数据中获取目标微服务真实的 BaseUrl 和内部 RPC 路径。
鉴权清洗与注入 (AuthGuard)：
请求在进入代理转发逻辑前，会先经过一道严格的鉴权守卫 AuthGuard。BFF 会提取前端请求中携带的 Token，不仅验证其签名和有效期，还会查询 Redis 中的用户会话（Session）以确认其真实性。
关键动作：BFF 在这一步会将外部传入的、可能不安全的凭证（如 Cookie、原始 Token）彻底"清洗"掉。然后，在转发给后端微服务的请求头中，极其确定地注入一个 X-USER-ID。这样一来，下游的微服务彻底解放，它们不再需要关心"如何解密 Token"，只要读取请求头里的 X-USER-ID，就可以百分之百地信任这个请求的身份。
环境标的智能注入：
对于多环境路由，BFF 实现了完全的自动化。如果运维或开发同学在 BFF 的管理后台将当前 Namespace 的环境切换到了 PPE，那么 BFF 在代理转发时，会自动在请求头中打上 X-TT-ENV=ppe 的标签。前端代码一行环境变量都不用修改，就能在各套测试环境间无缝漫游，彻底告别手动维护环境配置的痛苦。
微服务版本的灵活切换： 不同于传统方案中微服务版本被硬编码在前端配置里，BFF 支持在管理后aps.bytdiance.com台上动态配置每个 Namespace 下各微服务的版本。这意味着同一个前端应用，在不同的 Namespace 下，可以自动调度到完全不同的微服务实例。A 客户使用的是 v2.3.1 版本的用户服务，B 客户可能已经在体验 v2.4.0 了，而这种版本差异对前端完全透明。
跨域的彻底消解： 由于所有的前端请求都先打到同域的 BFF，再由 BFF 转发到各个微服务，浏览器根本感知不到跨域的存在。CORS 配置从此不再是前端的噩梦，后端微服务也无需各自配置 CORS 头，BFF 统一处理。
Proxy 模块是 BFF 的"万能翻译官"，把前端发送的约定式请求，精准地翻译成后端微服务期望的 RPC 调用。
Namespace 模块是 BFF 的"空间隔离官"，确保不同租户、不同业务线的配置与权限老死不相往来。
有了这两道防线，前端终于可以安心写业务，后端也能专注写服务，运维更是从此告别"环境噩梦"。
接下来笔者会开始着重讲解NmaeSpace的细节逻辑
LeetCode 上一道经典的位运算题目——190. 颠倒二进制位。这道题看似简单，实则藏着位运算的核心技巧，尤其是第二种“分治颠倒”的思路，非常值得深入理解，既能巩固位运算基础，也能锻炼逻辑思维。
先明确题目要求：给定一个 32 位有符号整数，将其二进制位全部颠倒，返回颠倒后的整数。比如输入二进制 00000010100101000001111010011100，输出就是 00111001011110000010100101000000。
这是最直观的思路：从原数字的最低位（最右边）开始，依次取出每一位二进制数，然后将其放到结果的对应高位（最左边），循环 32 次（因为是 32 位整数），最终得到颠倒后的结果。
先看完整代码：
function reverseBits_1(n: number): number {
let rev = 0; // 存储颠倒后的结果，初始为0（二进制全0）
// 循环32次（覆盖32位），若n提前变为0，可提前退出（优化效率）
for (let i = 0; i < 32 && n !== 0; ++i) {
// 1. 取出n的最低位：n & 1（二进制中，只有最低位是1时结果为1，否则为0）
// 2. 将取出的最低位移到对应高位：<< (31 - i)（第i次循环，对应31-i位）
// 3. 用或运算（|）将该位存入rev，不影响已存入的高位
rev |= (n & 1) << (31 - i);
// 4. n右移1位（无符号右移>>>），丢弃已处理的最低位，准备处理下一位
n >>>= 1;
}
// 无符号右移0位，确保结果是32位无符号整数（避免符号位干扰）
return rev >>> 0;
}
n & 1：这是位运算中“取最低位”的经典操作。比如 n=5（二进制 101），n&1=1（取最低位1）；n=4（100），n&1=0（取最低位0）。
<< (31 - i)：循环第 i 次（从0开始），我们取出的是原数字的第 i 位（从右数），需要放到结果的第 31 - i 位（从右数，即从左数的对应位置）。比如 i=0 时，取最低位，放到最高位（31位）；i=31时，取最高位，放到最低位（0位）。
n >>>= 1：这里必须用无符号右移（>>>），而不是有符号右移（>>）。因为如果是有符号整数，右移时符号位会补1，导致处理负数时出错；无符号右移会在高位补0，符合32位无符号整数的处理逻辑。
return rev >>> 0：同样是为了确保结果是32位无符号整数。在TypeScript/JavaScript中，整数可能会有符号位，无符号右移0位可以将其转为无符号数，避免因符号位导致的结果错误。
优点：思路简单，容易理解，代码量少，适合新手入门位运算。
缺点：循环32次，时间复杂度是 O(32) = O(1)（固定循环次数，属于常数时间），效率其实不低，但还有更优的“分治”思路，可以减少位运算的次数。
这种思路借鉴了“分而治之”的思想：将32位二进制数拆分成更小的单元（2位、4位、8位、16位），先颠倒每个小单元内部，再将颠倒后的小单元整体颠倒，最终实现整个32位的颠倒。
核心原理：利用位掩码（mask）分离出不同长度的单元，通过“右移+与掩码”“左移+与掩码”的组合，实现单元内部的颠倒，再合并单元。
完整代码：
function reverseBits_2(n: number): number {
// 定义4个位掩码，用于分离不同长度的二进制单元
const M1 = 0x55555555; // 01010101 01010101 01010101 01010101（每2位一组，01交替）
const M2 = 0x33333333; // 00110011 00110011 00110011 00110011（每4位一组，0011交替）
const M4 = 0x0f0f0f0f; // 00001111 00001111 00001111 00001111（每8位一组，00001111交替）
const M8 = 0x00ff00ff; // 00000000 11111111 00000000 11111111（每16位一组，0000000011111111交替）
let result: number = n;
// 第一步：颠倒每2位（比如 01 → 10，10 → 01）
result = ((result >>> 1) & M1) | ((result & M1) << 1);
// 第二步：颠倒每4位（比如 0011 → 1100，0101 → 1010）
result = ((result >>> 2) & M2) | ((result & M2) << 2);
// 第三步：颠倒每8位
result = ((result >>> 4) & M4) | ((result & M4) << 4);
// 第四步：颠倒每16位
result = ((result >>> 8) & M8) | ((result & M8) << 8);
// 最后：颠倒整个32位（前16位和后16位互换），并转为无符号整数
return ((result >>> 16) | (result << 16)) >>> 0;
}
假设我们有8位二进制数 11001010，用分治思路颠倒的过程如下：
每2位颠倒：拆分为 11、00、10、10，颠倒后为 11、00、01、01，合并为 11000101；
每4位颠倒：拆分为 1100、0101，颠倒后为 0011、1010，合并为00111010；
每8位颠倒：拆分为 0011、1010（此时8位拆分为两个4位），颠倒后为 10100011，即最终颠倒结果。
32位的逻辑和8位完全一致，只是拆分的单元更长，通过4个掩码逐步实现“从小单元到整体”的颠倒。
位掩码的作用：比如 M1（0x55555555），二进制每2位为一组，每组是01，用它和result做“与运算”，可以只保留result的奇数位（第1、3、5...31位）；同理，M2保留每4位的前2位，M4保留每8位的前4位，M8保留每16位的前8位。
颠倒单元的核心操作：以 ((result >>> 1) & M1) | ((result & M1) << 1) 为例：
(result >>> 1) & M1：将result右移1位，再和M1做与运算，得到“原奇数位右移1位”的结果（即原奇数位变成偶数位）；
(result & M1) << 1：将result和M1做与运算，得到原奇数位，再左移1位（即原奇数位变成偶数位）；
两者用或运算（|）合并，就实现了“每2位颠倒”。
效率优势：整个过程只需要5次位运算（4次单元颠倒+1次整体颠倒），无论输入是什么，都不需要循环，时间复杂度依然是 O(1)，但实际运算次数比解法一更少，效率更高。
优点：高效简洁，位运算技巧性强，适合深入理解位掩码和分治思想，在面试中写出这种解法，能体现对位运算的熟练掌握。
缺点：思路相对抽象，需要理解位掩码的作用和分治的拆分逻辑，新手可能需要多琢磨几遍。
| 解法 | 时间复杂度 | 空间复杂度 | 特点 | 适用场景 |
|---|---|---|---|---|
| 逐位颠倒（解法一） | O(1) | O(1) | 思路简单，易理解，循环32次 | 新手入门、快速解题、面试中快速写出正确代码 |
| 分治颠倒（解法二） | O(1) | O(1) | 技巧性强，运算次数少，效率高 | 深入理解位运算、面试加分、追求代码简洁高效 |
忘记用无符号右移（>>>）：无论是处理n还是结果，都必须用无符号右移，否则符号位会干扰，导致负数处理出错。
循环次数不足32次：即使n提前变为0，也需要循环32次（或者最后用rev >>> 0补全32位），否则会导致高位补0不完整，结果错误。
位掩码记错：解法二中的4个掩码是固定的，记错掩码会导致拆分单元错误，最终结果出错，建议记住这4个常用掩码（对应2、4、8、16位拆分）。
LeetCode 190题是位运算的经典入门题，两种解法各有优势：解法一胜在易懂，解法二胜在高效。建议新手先掌握解法一，理解“逐位取数、逐位放置”的核心逻辑，再深入研究解法二的分治思想和位掩码技巧。
其实位运算的核心就是“操作二进制的每一位”，多练习这类题目，就能慢慢掌握各种位运算技巧（比如取位、移位、掩码、或/与/异或运算），后续遇到更复杂的位运算题目（如位1的个数、两数相加等）也能迎刃而解。
在科学计算、图像处理和机器学习领域，数组中出现 NaN（Not a Number）或 Inf 是常见问题。当数据规模达到 10⁸ 以上时，如何快速定位所有 NaN 值的索引位置，成为一项具有挑战性的任务。本文将从技术实现、性能优化和线程模型等维度，全面比较 GPU 与 CPU 上高效检测 NaN 值的三种方案。
NaN 值通常是数值溢出、除以零、未初始化或异常操作的结果。一旦进入后续的归一化、矩阵运算或模型训练流程，可能导致整个计算结果失效。在大规模数据分析中，若不及时发现和定位 NaN，后续逻辑可能产生巨大偏差。
虽然判断单个值是否为 NaN 看似简单（调用 isnan() 或比较 x != x），但当数据规模庞大时，存储访问、线程同步和写操作成本成为性能瓶颈。
本文比较三条技术路线：
利用 OpenMP 的多线程机制，将数组划分为多个区间，每个线程独立扫描并收集本地 NaN 索引，最后合并结果。这是最容易实现的方案，兼容性好且便于调试，但受限于 CPU 内存带宽，在大规模数据上性能较差。
#pragma omp for
for (size_t i = 0; i < N; ++i)
if (std::isnan(data[i]))
local_indices.push_back(i);
优化建议：预分配 vector 容量，避免频繁的 push_back 扩容操作。
利用 thrust::counting_iterator 生成索引序列，以数据数组作为判断条件，使用 thrust::copy_if 将 NaN 位置的索引压缩输出。该方法无需原子操作，输出索引自动升序排列，整体稳定高效。
auto end_it = thrust::copy_if(
thrust::counting_iterator<int>(0),
thrust::counting_iterator<int>(N),
d_data_ptr, d_out_ptr, is_nan_pred());
size_t num_nans = end_it - d_out_ptr;
自定义 CUDA Kernel，每个线程判断一个或多个元素。当检测到 NaN 时，通过 atomicAdd 获取写入位置并记录索引。该方案在 NaN 极度稀疏时性能最优，因为写操作极少；但当 NaN 数量较多时，原子操作冲突会显著降低效率。
__global__ void collectNaNAtomic(const float* data, size_t N, int* out_idx, int* counter) {
size_t idx = blockIdx.x * blockDim.x + threadIdx.x;
if (idx >= N) return;
if (isnan(data[idx])) {
int pos = atomicAdd(counter, 1);
out_idx[pos] = (int)idx;
}
}
| 方案 | 核心思想 | 优点 | 缺点 |
|---|---|---|---|
| CPU + OpenMP | 多线程扫描，收集索引 | 易于调试，兼容性好 | 内存带宽受限，大规模慢 |
| GPU + Thrust copy_if | 索引流压缩 | 稳定高效，输出有序 | 写量多时有开销 |
| GPU + atomicAdd | 原子计数写索引 | 稀疏 NaN 时极快 | NaN 多时冲突大 |
选择哪种方案取决于 NaN 的稀疏程度和数据规模。对于一般场景，Thrust copy_if 是最稳妥的选择；当 NaN 极稀疏时，atomicAdd 方案可能更快；而 CPU 方案适合无 GPU 环境或调试阶段使用。
本文来源于公众号「梁柱墙笔记」，原文链接：mp.weixin.qq.com/s/kjUspLi-g…
