莫莫的博客

Vue 3 响应式原理

Wed, 27 May 2026 00:00:00 GMT

一句话摘要

Vue 3 的响应式核心，是通过 Proxy 拦截读写操作，再借助 effect、track、trigger 和依赖映射表，把数据读取和副作用函数重新执行关联起来。

一句话摘要
目录
核心数据结构
核心函数
响应式更新流程
如何拦截 set 和 get
反射和代理
加入 track 和 trigger
详细运行过程
第三步的延伸：如果在外部再加入一个独立的 get 操作，会有什么问题吗？
- 本章小结
ref 的实现
computed 的实现
- 本章小结
总结

核心数据结构

三个表：targetMap（WeakMap）、depsMap（Map）、dep（Set）。

Vue 内部维护了一个全局的弱引用映射字典（WeakMap），数据结构大概是：

target（被代理对象） -> key（对象属性） -> Set<effect>

对应关系如下：

targetMap：key 是对象，value 是属性表。
depsMap：key 是属性，value 是 effect 表。
dep：value 是 effect。

核心函数

三个函数：effect、track、trigger。

1. effect：副作用函数

effect 接收一个函数 fn。当你调用 effect(fn) 时：

它会立即执行一次 fn。
在执行 fn 的过程中，如果读取了响应式数据（比如 reactive 生成的 Proxy 对象属性），就会触发该属性的读取拦截器（getter）。
建立起被访问数据与这个 fn 之间的联系，以便将来数据变化时，这个 fn 能够被再次执行。

2. track：依赖收集

track 一般在响应式对象（Proxy）的 get（读取）操作拦截器中被内部调用。

其核心作用是把当前正在运行的 effect 记录下来。

3. trigger：派发更新

trigger 一般在响应式对象（Proxy）的 set（修改）操作拦截器中被内部调用。

其核心作用是取出对应的 effect 并执行。

响应式更新流程

effect(fn) -> 执行 fn()
读取数据触发 Proxy getter -> 调用 track 收集 activeEffect
修改数据触发 Proxy setter -> 调用 trigger 取出 effect -> 重新执行 effect(fn)

如何拦截 set 和 get

Vue 2：ES5 Object.defineProperty()
Vue 3：ES6 Proxy

反射和代理

代理（Proxy）是一个对象的占位符，默认情况下对该对象进行委托。

Proxy() 的第二个参数叫处理函数（Handler），可以传递一个诱捕器（trap），用于拦截各种基础操作，比如属性查找、枚举，我们就可以用来拦截 get 和 set 了。

function reactive(target) {
  const handler = {
    get(target, key, receiver) {
      console.log('触发了 Get，key = ' + key);
      return Reflect.get(target, key, receiver);
    },
    set(target, key, value, receiver) {
      console.log('触发了 Set，key = ' + key + '，value = ' + value);
      return Reflect.set(target, key, value, receiver);
    }
  };

  // 返回一个代理对象，我们可以像使用原对象一样使用它。
  return new Proxy(target, handler);
}

let product = reactive({ price: 5, quantity: 2 });

注意：receiver（接收器）的作用是保证当我的对象有继承自其他对象的值或函数时，this 指针能正确指向使用的对象。

加入 track 和 trigger

再加入 track 和 trigger：

function reactive(target) {
  const handler = {
    get(target, key, receiver) {
      let result = Reflect.get(target, key, receiver);
      track(target, key); // 收集依赖
      return result;
    },
    set(target, key, value, receiver) {
      let oldValue = target[key];
      let result = Reflect.set(target, key, value, receiver);
      // 只有当值发生改变时才触发更新
      if (oldValue !== value) {
        trigger(target, key); // 派发更新
      }
      return result;
    }
  };

  return new Proxy(target, handler);
}

let product = reactive({ price: 5, quantity: 2 });

然后我们尝试创建一个对象，并且使用上面的 reactive 方法：

let product = reactive({ price: 5, quantity: 2 });
let total = 0;

let effect = () => {
  total = product.price * product.quantity;
};

effect(); // 初始执行，触发 getter 依赖收集
console.log(total); // 输出 10

product.quantity = 3; // 触发 setter 派发更新
console.log(total); // 输出 15

详细运行过程

1. 建立响应式对象

我们通过 reactive({ price: 5, quantity: 2 }) 创建对象，它返回了一个 Proxy 代理对象 product。此时 product 的读取（get）和修改（set）操作都已经分别被拦截处理。

2. 初次执行 effect 并收集依赖（track）

手动调用执行 effect() 时，它内部读取了 product.price 和 product.quantity。此时触发了代理对象 product 的 get 拦截器。

在 get 拦截器中，内部调用了 track(target, key)：

track 把当前的 effect 副作用函数收集到全局依赖字典（targetMap -> depsMap -> dep）中，分别与 price 和 quantity 这被访问的属性建立联系。
total 计算结果为 5 * 2 = 10。

3. 修改数据并自动派发更新（trigger）

当代码走到 product.quantity = 3 时，是对 product 属性赋值，此操作触发了代理对象的 set 操作拦截器。

在 set 拦截器中：

我们传入的新值 3（value）和原来的值 2（oldValue）不相等，即判定 oldValue !== value 成立。
由于值发生了变化，拦截器继续调用 trigger(target, 'quantity') 发出更新派发信号。
trigger 去全局依赖字典找到订阅在当前对象 'quantity' 属性上的所有 effect 函数集合并执行它们。
这样我们原本的 effect 函数就会重新隐式运行一遍（total = 5 * 3），从而使 total 更新为 15。
所以最后一句 console.log(total) 时，得到的是最新的结果 15。

本章小结

这个例子完整串起了初始化执行、读取收集、赋值触发和副作用重跑四个环节。最终 total 从 10 更新为 15，正是 trigger 派发更新后的结果。

第三步的延伸：如果在外部再加入一个独立的 get 操作，会有什么问题吗？

假如我们在最下面直接加上一句：

console.log('Updated quantity to = ' + product.quantity);

答案是：有可能会导致错误收集。

当你执行 product.quantity 这一读取操作时，自然会再次触发 Proxy 代理对象的 get 拦截器。而在 get 拦截器内，会不可避免地自动执行 track(target, key) 去收集依赖。

问题在于这里所处的上下文：这段 console.log 代码是在全局下直接运行的，它并没有被包裹在任何副作用 effect 函数内。

如果没有进行安全判断：我们的 track 函数可能会去收集那个根本不存在的依赖（可能是 undefined，也可能是上次残留还没被清除的旧 effect），将一个无效的依赖强行塞进我们的 dep 集合里，这会导致内存泄漏，甚至是调用报错。

这就引出了真正完善的依赖收集机制里非常关键的一环：在真正的 Vue 3 源码中，内部会维护一个全局变量（通常命名为 activeEffect）来时刻保存当前正在执行的副作用函数。在进入 effect 执行时赋值给它，出 effect 时清空。

而 track 在尝试收集依赖之前，做的第一件事就是检查 activeEffect 是否存在。只有存在才会把它添加进弱映射字典，以防止脱离副作用的“越界收集”。

本章小结

依赖收集必须建立在当前确实存在 activeEffect 的前提下。脱离副作用函数的读取操作不能被随意收集，否则可能产生无效依赖、内存泄漏或调用报错。

ref 的实现

对于基本数据类型（如字符串、数字等），由于它们不是对象，我们无法给它们应用 Proxy 代理。因此，Vue 的方案是用一个对象包裹它，这就是 ref。

ref 的核心是利用了对象访问器（Getter / Setter 计算属性）来获取或设置 .value 的值：

function ref(raw) {
  const r = {
    get value() {
      track(r, 'value'); // 收集依赖
      return raw;
    },
    set value(newVal) {
      if (raw !== newVal) {
        raw = newVal;
        trigger(r, 'value'); // 派发更新
      }
    }
  };
  return r;
}

computed 的实现

function computed(getter) {
  let result = ref();

  // 每次 getter 里的依赖数据变化时，effect 都会重新执行，给 result.value 赋予新计算的值
  effect(() => {
    result.value = getter();
  });

  return result;
}

let product = reactive({ price: 5, quantity: 2 });

let salePrice = computed(() => {
  return product.price * 0.9;
});

let total = computed(() => {
  return salePrice.value * product.quantity;
});

console.log(total.value); // 此时由于依赖响应式数据改变，总价会自动重算

注意：源码实际上的处理方式（基于 ComputedRefImpl）是真正的 computed 是一个带有懒计算标志位（_dirty）的对象。

依赖发生改变时，它并不立即运算求新值，而是通过传入 scheduler 调度器把 _dirty 标记为 true（脏数据），这相当于告诉 Vue：“我的值已经过期了”。

只有当你再次读取 salePrice.value 触发访问时，Vue 发现 _dirty 为 true，才会重新调用 getter() 执行真正的计算，算出新值后存起来并将 _dirty 置为 false。

这期间如果没有依赖发生变更（_dirty 依然是 false），它会一直直接返回上次计算缓存的值，绝不重复运算。

本章小结

简化版 computed 可以用 ref 和 effect 拼出来；源码里的 computed 还会通过 _dirty 和 scheduler 做懒计算与缓存，避免每次读取都重复执行 getter()。

总结

Vue 3 响应式系统可以按一条主线理解：用 Proxy 拦截对象的读取和修改，在读取时通过 track 收集当前 activeEffect，在修改时通过 trigger 找到并重新执行对应的副作用函数。

ref 解决的是基本数据类型不能直接被 Proxy 代理的问题；computed 则是在响应式依赖之上加入计算、缓存和懒更新机制。理解这几层关系后，再看 reactive、ref、computed 的行为，就能更容易串起 Vue 3 响应式的整体流程。

RAG 知识库搭建经验总结

Thu, 21 May 2026 00:00:00 GMT

一句话摘要

这篇文章复盘了一套 RAG 知识库从分片、向量化、召回、重排到生成的落地过程，并整理了前后端技术选型、业务链路和实际踩坑。

背景与问题

标准 RAG（检索增强生成）的核心流程可以概括为：分片 -> 索引 -> 召回 -> 重排 -> 生成。

在这个流程里，系统会先把文章或资料切成 Chunk，再通过 Embedding 模型将每个片段转换为向量，并存入向量数据库。用户提问时，问题本身也会被转换为向量，系统再从向量数据库中检索出语义最相近的 $n$ 个片段。

接下来，系统会用 Cross-encoder 模型对召回结果进行重排，筛选出相关度最高的 $m$ 个片段。最后，将用户问题和这些高相关片段一并输入给大模型，生成最终回答。

本章小结

RAG 的本质是把“可靠资料检索”接入大模型生成链路，本质就是上下文工程，给大模型提供参考资料。

关键思路

这次项目的后端用 Node.js / Hono，前端用 Vue3，向量数据库基于 Docker + PGVector 搭建，AI 协调控制技术栈选择 LangChain + Vercel AI SDK。

它们在系统中的职责划分如下：

PGVector：作为向量数据库，利用 Docker 快速容器化部署 PostgreSQL，并加载 PGVector 插件，提供本地化向量存储和相似度匹配服务。
LangChain.js：负责后端的数据加载、文本切片、文档对象构建，以及向向量数据库发起检索。
Vercel AI SDK：负责大模型调用、流式数据通讯和前端 UI 状态接管，减轻前端处理流式响应的负担。

为什么需要 Vercel AI SDK

如果不使用 Vercel AI SDK，在 Vue3 中手工开发 AI 对话界面会遇到不少重复问题。

首先是 SSE 或 ReadableStream 的解析。后端返回的通常不是完整 JSON，而是连续的数据流，前端需要手动处理 Chunk 解码、字符串拼接和异常状态。

其次是打字机效果。每次收到数据碎片，都要手动更新消息数组；如果渲染节奏控制不好，很容易引发界面卡顿或频繁重绘。

最后是状态管理。isLoading、停止生成、重新生成、上下文消息数组等状态都需要手动维护，代码很容易变得松散。

Vercel AI SDK 在 Vue 项目中可以通过 @ai-sdk/vue 接管这些状态。UI 直接循环渲染 messages，输入框绑定 input，提交绑定 handleSubmit，加载状态绑定 isLoading，整体实现会轻很多。

它也支持生成式结构化输出（Generative UI）。当需要 AI 返回“目标、热量、餐次”等结构化 JSON 数据时，SDK 可以在接收碎片流期间逐步处理内容，甚至驱动前端生成动态交互组件。

本章小结

后端用 LangChain 管检索链路，底层数据的向量存储交由 PGVector，前端和模型流式交互交给 Vercel AI SDK。这样分工后，系统边界清晰，前后端都不用重复处理多余的组件底座工作。

实践过程

在具体落地时，LangChain 服务端的各个核心组件（Loaders、Splitters、Embeddings、Vector Stores）并没有通过 RunnableSequence 强行声明式串联，而是分散在导入脚本和 RAG 检索层中进行了灵活组装。

步骤1：业务链路与数据融合

在基础 RAG 问答能力之上，这个项目重点融合了用户本地数据。整体处理链路分为四步：

读取本地用户数据：通过 SQL 从浏览器 IndexedDB 中读取身高、体重、近期体重变化、热量摄入等属性数据。
知识库向量检索：将用户问题向量化，在 PGVector 中检索相关的专业知识内容。
融合提示词：把“用户本地私有数据”、“向量库返回的专业资料”和“用户原始问题”汇总并拼装成完整的 Prompt。
大模型生成：后端将组装好的 Prompt 发给模型，然后利用 Vercel AI SDK 将数据平滑流式地返回给前端展示。

这条链路的重点突破：本地系统数据解决“个性化背景限制”，知识库检索解决“干货专业依据缺乏”，这两只手抓稳后双管齐下交由大模型统筹整合。

步骤2：数据加载与切块（Loaders & Splitters）

首先，需要从源文件（例如 PDF）中提取文本，并使用 Document Loaders 转换为 LangChain 的 Document。在此步骤我们同时注入了页码、书名等 Metadata，为的是日后给解答提供清晰的引用原出处：

import { Document } from '@langchain/core/documents'

export const createKnowledgeDocumentsFromPages = ({ filePath, pages }: CreateKnowledgeDocumentsOptions) => {
  const bookTitle = inferBookTitleFromFileName(filePath)

  return pages.flatMap(({ pageNumber, text }) => {
    const pageContent = cleanKnowledgeText(text)

    return [
      new Document({
        metadata: { bookTitle, pageNumber, source: filePath },
        pageContent,
      }),
    ]
  })
}

针对整块长文档，项目接着使用了分块器 RecursiveCharacterTextSplitter 进行更小粒度的切割（Splitters）：

new RecursiveCharacterTextSplitter({
  chunkOverlap: 300,
  chunkSize: 1500,
})

这里限制每个文本块约保留 1500 字符，冗余重叠 300 字符。保留重叠字符是常见但也特别必须的做法，能有效减少连续语义段落正好被“一刀两断”从而在检索中匹配度过低的问题。

步骤3：向量化与入库（Embeddings & Vector Stores）

切分完毕后，再次利用 OpenAIEmbeddings 以及 PGVectorStore 发起 Embedding 从而在向量库（Vector Stores）进行落库存储。

import { PGVectorStore } from '@langchain/community/vectorstores/pgvector'
import { OpenAIEmbeddings } from '@langchain/openai'

export const createKnowledgeVectorStore = async () => {
  const { collectionName, connectionString, tableName } = getRagRuntimeConfig()

  return PGVectorStore.initialize(new OpenAIEmbeddings({...}), {
    collectionName,
    collectionTableName: `${tableName}_collections`,
    postgresConnectionOptions: { connectionString },
    tableName,
  })
}

实际通过脚本批量写入时，必须使用分块批处理循环写入以控制节奏：

for (let index = 0; index < chunks.length; index += batchSize) {
  await vectorStore.addDocuments(chunks.slice(index, index + batchSize))
}

避坑踩雷点：在起初导入时遇到了大量的超速失败返回，我最终把 batchSize 强行从官方默认经验值的 50 压到了 10 才安全导入完成避免接口速率限制断连。

步骤4：检索召回流（Retriever Pipeline）

这一步，当用户提问时，我们会将上面初始化的 PGVectorStore 实例转为正式的检索器（Retriever），并调用 .invoke 向模型发起近似语句匹配。这也是虽然没用显式 Runnable 管道串联，但这完全执行了相同手撕控制流的地方。

export const createKnowledgeRetriever = async () => {
  const { k } = getRagRuntimeConfig()
  const vectorStore = await createKnowledgeVectorStore()

  return vectorStore.asRetriever({ k })
}

export const getKnowledgeContext = async (question: string, {...}) => {
  const retriever = await createRetriever()
  const documents = await retriever.invoke(question)

  return formatKnowledgeContext(documents)
}

代码中的 k 代表你要让他在库里回捞排名前几最相似的资料条（设为 5）。不能盲目求多：如果召回偏少固然会错失某些要点，但无限度扩大后更会引发严重的文不对题噪音，而且直接把一堆没用的废话喂给 LLM 会消耗大量不必要的 Token 计费。这一个收尾逻辑，实现了真正的 RAG Pipeline 运作链路过程：

存入流：PDF原始数据 -> Loaders转为Document -> Splitters分块切分 -> Embeddings化 -> PGVector存储
检索流：提问触发请求 -> retriever召回最相似片段 -> 附并私有数据合并出终极Prompt -> 交给聊天大模型 -> 前端流式收尾展示

本章小结

回顾这个实践脉络会发现：数据层囊括了原文档解析与 Embedding 赋能，检索层揽收下了文本找回与大锅烩操作，再借由大模型与 Vercel 的生成能力构成生成展示层，由此跑通了一个有逻辑的完整 RAG 工作流架构。

结果与复盘

PDF 解析问题

一开始下的书籍是 PDF 版本，用 pdf-parse 转文本后发现很多书是空页。问ai才知道需要 OCR 处理的版本。然后又去网上找了 OCR 版本的 PDF 才成功导入。

批量导入过大

向量化导入数据库时，把每次导入的 Batch Size 从默认的 50 调小到 10，才没有触发 Embedding 接口速率限制。

结构化输出

最初允许 AI 一次生成任意时长的计划，但后来发现当计划超过 14 天时，输出规模会变得过大，后段很容易遭遇内容截断或 JSON 格式错误。

解决方式有三点：

从产品侧限制单次最多生成 1-14 天的计划。
使用 JSON output 属性，增加预置 JSON 结构的 Prompt 要求。
增加强验证机制。如果系统校验到错乱 JSON，就拒绝输出结果，并把错误输出和标准示例再次交给 AI 重整。

TDD

这次实践也让我更深刻地认识到 TDD（测试驱动开发）的重要性。现在已经通过提示词限制，例如 Codex 的 agent.md，强制要求 AI 每次动及源码时都遵循 TDD 模式开发。

也就是：先写预期失败的前置测试 -> 编写业务逻辑 -> 本地测试通过后才视为完成。

这种约束方式配合全量回归测试，可以给后续迭代划定明确边界，也能最大程度降低 AI 修改新逻辑时悄悄破坏老功能的风险。

从手动上传到自动发布：我给项目接入 CI/CD 的完整复盘

Wed, 13 May 2026 00:00:00 GMT

一句话摘要

这篇文章复盘了我把一个 Vue + Vite + PWA 项目从手动上传改造成 GitHub Actions 自动发布的全过程。真正有价值的部分，不只是部署自动化本身，而是如何把发布链路变成一个可重复、可验证、可排查的流程。

背景与问题

这次折腾 CI/CD，起点其实很简单：我不想每次改完网站后，还要一遍遍手动上传。

原来的流程是：

本地改完代码。
手动上传到 GitHub。
再手动上传到腾讯云。
再手动刷新网站。

如果只是偶尔改一次，这样做还能忍。但一旦进入频繁迭代阶段，这套流程会越来越烦，而且非常容易出错。

所以这次的目标很明确：

以后只要 git push，网站就自动检查、自动打包、自动上传、自动切到新版本。

本章小结

这次改造主要是为了减少手动发布带来的重复劳动。

最终方案

最终跑通的链路是这样的：

本地改代码，提交到 GitHub。
GitHub Actions 自动执行安装依赖、类型检查、测试和打包。
GitHub Actions 通过 SSH 把打包结果传到 Lighthouse。
服务器执行发布脚本，把文件解压到新的版本目录。
服务器把 current 指向这个新版本。
OpenResty 继续对外提供网站。

对应到仓库里，关键文件有两个：

yml工作流文件
OpenResty 配置

简单说，这套方案的核心思想就是：

GitHub 负责“打包和上传”，服务器负责“接收和切换版本”。

我的线上环境是：

腾讯云 Lighthouse
1Panel
OpenResty
Vue + Vite + PWA 前端项目

这意味着我不是纯静态托管平台，也不是 Docker 编排方案。我已经有一台稳定运行的网站服务器，所以最合适的方式不是重新迁移平台，而是保留 Lighthouse + 1Panel + OpenResty，只把“手动发布”改成“自动发布”。

本章小结

这次方案的关键不是引入更多基础设施，而是在现有环境上补齐自动化发布能力，让 GitHub Actions 和服务器各自负责清晰的一段。

实践过程

步骤 1：调整服务器目录结构

以前网站文件直接放在一个固定目录里，比如：

/opt/1panel/www/sites/calorie/index

为了支持自动发布和多版本切换，我把目录改成了这种结构：

/opt/1panel/www/sites/calorie/
  index
  releases/
    first/
    1bc469d390d5d8f2094763ce9273f05aef7e1d59/
  current -> releases/1bc469d390d5d8f2094763ce9273f05aef7e1d59

这里最关键的是两个概念：

releases/：保存每次发布后的版本目录。
current：当前线上正在使用的版本。

这样以后每次发布，都只是新建一个版本目录，把新文件解压进去，再把 current 切过去。

步骤 2：让 OpenResty 读取 `current`

服务器这边不是系统自带 Nginx，而是 1Panel 管理的 OpenResty。

最后生效的思路是：

宿主机路径用 /opt/1panel/...。
OpenResty 配置里的路径用 /www/sites/...。

OpenResty 配置里核心是这两句：

root /www/sites/calorie/current;
index index.html;

此外，Vue Router 我使用的history路由模式，所以必须加上：

location / {
    try_files $uri $uri/ /index.html;
}

否则像 /history、/profile 这种页面，直接刷新就会 404。

步骤 3：编写服务器发布脚本

服务器上放了一个简单脚本，用来完成“解压新版本 + 切换 current”。

最终版本是：

#!/usr/bin/env bash
set -e

APP_DIR="/opt/1panel/www/sites/calorie"
ARCHIVE_PATH="$1"
VERSION_NAME="$2"

RELEASE_DIR="$APP_DIR/releases/$VERSION_NAME"

mkdir -p "$RELEASE_DIR"
tar -xzf "$ARCHIVE_PATH" -C "$RELEASE_DIR"
ln -sfn "releases/$VERSION_NAME" "$APP_DIR/current"
rm -f "$ARCHIVE_PATH"

cd "$APP_DIR/releases"
ls -1dt */ | tail -n +6 | xargs -r rm -rf

:::important 这里最关键的一行是 ln -sfn "releases/$VERSION_NAME" "$APP_DIR/current"。它必须使用相对路径软链接，不能写成指向宿主机绝对路径的软链接。 :::

步骤 4：生成 GitHub 用的 SSH 密钥

要让 GitHub 自动上传文件到 Lighthouse，就得让 GitHub 能通过 SSH 登录服务器。

流程是：

本地生成一对专门用于部署的密钥。
把公钥放到服务器的 authorized_keys。
把私钥放到 GitHub Secrets。

我在本地测试过：

ssh -i "$env:USERPROFILE\.ssh\calorie_lighthouse" root@服务器ip地址

能正常登录，就说明这一步成功。

步骤 5：配置 GitHub Secrets

在仓库的设置里添加这 4 个 Secrets：

LIGHTHOUSE_HOST：服务器的 IP 地址
LIGHTHOUSE_PORT：服务器的 SSH 端口
LIGHTHOUSE_USER：SSH 登录用户名
LIGHTHOUSE_SSH_KEY：生成的私钥私钥内容

:::caution[小提醒]

GitHub 里放的是私钥文本。
服务器里放的是公钥。
不要把 .pub 公钥文件填进 GitHub。

:::

步骤 6：添加 GitHub Actions 工作流

工作流文件位置：

.github/workflows/deploy.yml

它做的事情是：

拉代码。
安装依赖。
跑 pnpm type-check。
跑 pnpm test。
跑 pnpm build。
把 dist 同步到服务器的新版本目录。
把 current 切到新版本。

一开始我用的是 tar -czf dist.tar.gz -C dist .，也就是先压缩，再上传，再解压。

这个方案很直观，但如果站点里有大量图片、音频这类已经压缩过的静态资源，tar.gz 的收益会很小。比如一个 699MB 的 dist，压缩后可能仍然有 680MB 以上。

后面我把上传方式改成了 rsync 增量同步。核心命令是：

- name: Sync dist to server
  run: |
    rsync -az --delete \
      --link-dest=/opt/1panel/www/sites/calorie/current \
      -e "ssh -i ~/.ssh/deploy_key -p ${{ secrets.LIGHTHOUSE_PORT }} -o ServerAliveInterval=30 -o ServerAliveCountMax=20" \
      dist/ \
      "${{ secrets.LIGHTHOUSE_USER }}@${{ secrets.LIGHTHOUSE_HOST }}:/opt/1panel/www/sites/calorie/releases/${{ github.sha }}/"

这里的关键不是 rsync 本身，而是 --link-dest。

它会拿新版本目录和当前线上版本 current 做比较：

没变化的文件：直接硬链接上一版文件，不重新上传。
有变化的文件：才从 GitHub Actions 传到服务器。
服务器多出来的旧文件：通过 --delete 清理掉。

同步完成后，再执行：

- name: Activate release
  run: |
    ssh -i ~/.ssh/deploy_key \
      -p "${{ secrets.LIGHTHOUSE_PORT }}" \
      "${{ secrets.LIGHTHOUSE_USER }}@${{ secrets.LIGHTHOUSE_HOST }}" \
      "cd /opt/1panel/www/sites/calorie && test -f releases/${{ github.sha }}/index.html && ln -sfn releases/${{ github.sha }} current && cd releases && ls -1dt */ | tail -n +6 | xargs -r rm -rf"

这里先检查新版本目录里是否存在 index.html，再切换 current。这样即使同步中途失败，线上仍然停留在旧版本，不会切到半成品目录。

本章小结

整套实践过程可以拆成三层：GitHub Actions 负责构建和增量同步，服务器负责版本目录和软链接切换，OpenResty 负责读取当前版本并提供访问。

踩坑复盘

这部分是整次搭建里最有价值的部分。

坑 1：`pnpm/action-setup` 版本冲突

第一次跑 GitHub Actions 时，卡在了：

Error: Multiple versions of pnpm specified

原因是 package.json 里已经有：

"packageManager": "pnpm@10.28.0"

但工作流里又写了：

with:
  version: 10

这相当于在同一个地方声明了两份版本信息。

最后修法很简单：删除工作流里的 version: 10，保留 package.json 里的版本作为唯一来源。

坑 2：Lighthouse 上没有 `nginx` 命令

一开始我想直接执行：

sudo nginx -t
sudo systemctl reload nginx

结果报错：

sudo: nginx: command not found
Failed to reload nginx.service: Unit nginx.service not found.

这并不是配置错了，而是因为这台服务器不是系统直接装的 Nginx，而是 1Panel 管理的 OpenResty。

所以后面真正生效的操作方式不是 systemctl reload nginx，而是：

通过 1Panel 修改站点配置。
在 1Panel 里点击“重载”。

坑 3：宿主机路径和 OpenResty 容器路径不是一回事

这是本次最大的坑。

我一开始以为网站真实目录是：

/opt/1panel/www/sites/calorie/

所以 OpenResty 配置里也写成了：

root /opt/1panel/www/sites/calorie/current;

结果网站一直 500。

后面才发现：

在服务器 shell 里看到的是宿主机路径：/opt/1panel/...。
OpenResty 实际工作时看到的是容器里的路径：/www/sites/...。

所以正确做法是：

shell 命令里用 /opt/1panel/...。
OpenResty 配置里用 /www/sites/...。

这类容器映射问题，如果不搞清楚，很容易一直以为“目录都在，为什么网站还是坏的”。

坑 4：`current` 软链接用了绝对路径，导致 500

这次最关键的根因是：一开始我让 current 指向了宿主机绝对路径：

current -> /opt/1panel/www/sites/calorie/releases/xxx

看起来没问题，但 OpenResty 读这个链接时会顺着跳到 /opt/1panel/...，而对它来说那个路径并不存在。

于是它不断 fallback 到 /index.html，最后在日志里出现：

rewrite or internal redirection cycle while internally redirecting to "/index.html"

最后修法是把 current 改成相对路径软链接：

current -> releases/1bc469d390d5d8f2094763ce9273f05aef7e1d59

而不是：

current -> /opt/1panel/www/sites/calorie/releases/...

改完后，网站立刻恢复正常。

坑 5：浏览器显示旧页面，不代表服务器正常

这是一个很迷惑人的现象。

GitHub Actions 明明已经成功了，服务器里的 current 也已经切到了新版本，但浏览器里看起来网站“完全没变”。

最后排查发现：

服务器真实响应其实已经 500 了。
浏览器里显示的是旧的 PWA 缓存页面。

因为这个项目开了 PWA：

这意味着电脑和手机都可能继续显示旧缓存。哪怕服务器已经挂了，用户表面上也可能还能打开旧页面。

:::warning 排查线上问题时，应该先看服务器真实返回，再看浏览器表现。浏览器页面能打开，不等于服务器当前状态一定正常。 :::

像这次，如果先执行：

curl -I https://your-domain.com

就能很快发现服务器返回的是 500，而不是继续围着“为什么页面没更新”打转。

本章小结

这次踩坑集中在三类问题上：工具链配置重复、服务环境与预期不一致、浏览器缓存掩盖真实状态。真正节省时间的不是反复试，而是尽快确认每一层的真实状态。

增量部署的实现

增量部署这件事，表面上看是“少传点文件”，但真正要解决的是两个问题：

怎么判断哪些文件没变。
怎么保证同步失败时不影响线上版本。

最终我采用的是 rsync + --link-dest + current 软链接 这套组合。

为什么不是继续用压缩包

压缩包方案的链路是：

dist -> dist.tar.gz -> scp 到服务器 -> tar 解压 -> 切 current

它的优点是简单，所有文件都在一个包里，服务器只要解压就行。

但它有一个明显缺点：每次都是全量上传。

如果项目产物主要是 HTML、CSS、JS，tar.gz 的压缩收益通常还不错。但如果项目里有大量 JPG、PNG、MP3 这类文件，它们本身已经压缩过了，再套一层 gzip 基本省不了多少体积。

所以当 dist 里有几百 MB 的相册图片时，压缩包部署就会变成：

每次 push，都重新上传几百 MB。

这会让 GitHub Actions 到服务器之间的网络抖动被无限放大。上传一旦中断，服务器上还可能留下一个不完整的 .tar.gz。

`rsync --link-dest` 怎么做到增量

rsync 本身可以比较源目录和目标目录，只传变化部分。

但如果每次发布都同步到一个全新的 commit 目录，比如：

releases/e25e77d64d7eaac0dc81134f502456acade290de/

这个目录一开始是空的，rsync 仍然会认为所有文件都需要传一遍。

真正让它变成增量的是 --link-dest：

rsync -az --delete \
  --link-dest=/opt/1panel/www/sites/calorie/current \
  dist/ \
  root@服务器:/opt/1panel/www/sites/calorie/releases/<commit-sha>/

这行命令的意思是：

生成一个新的 release 目录，但如果某个文件和 current 里的文件完全一样，就不要重新上传，而是在新 release 里创建一个指向旧文件 inode 的硬链接。

这样看起来每个 release 都是完整目录：

releases/
  old-sha/
  new-sha/
current -> releases/new-sha

但磁盘和网络层面并不是每次都复制一整份。没变的大图、音频、字体文件，会直接复用上一版。

为什么还要保留 `current`

current 不只是给 OpenResty 读取当前版本，它还是增量部署的参照物。

部署时：

rsync 参考 current，生成新的 release 目录。
同步完成后，检查新目录里是否有 index.html。
检查通过后，才执行 ln -sfn releases/<commit-sha> current。
OpenResty 继续读取 /www/sites/calorie/current。

这个顺序很重要。

如果同步失败，current 还指向旧版本，线上不会受影响。只有新版本完整同步成功后，才会切换流量。

和压缩包部署相比，它解决了什么

增量部署解决了三个实际问题。

第一，上传量变小。

文章、样式、小脚本改动时，只需要传少量变化文件。几百 MB 的相册图片不会每次重新上传。

第二，失败影响更小。

同步失败时，新 release 最多是半成品，但 current 没切过去，线上仍然是旧版本。

第三，回滚方式不变。

因为最终结构仍然是：

current -> releases/<version>

所以回滚还是同一套命令：

ln -sfn releases/<old-version> current

增量部署只是改变“新 release 怎么生成”，没有改变“线上版本怎么切换”。

本章小结

增量部署的核心不是简单地把 scp 换成 rsync，而是让 rsync 通过 --link-dest=current 复用上一版文件，再用 current 软链接保证发布切换的原子性。这样既减少传输量，也保留了多版本发布和快速回滚的能力。

跑通后的完整链路

到最后，整套发布链路是这样工作的：

本地改代码。
提交到 main。
GitHub Actions 自动运行。
通过检查、测试、构建后，把 dist/ 增量同步到 Lighthouse 的新 release 目录。
服务器确认新 release 存在 index.html，再把 current 切到新版本。
OpenResty 继续从 /www/sites/calorie/current 对外提供网站。
网站更新完成。

这次成功的证据是：

GitHub Actions 成功。
deploy.sh 存在且可执行。
current 指向最新提交目录。
网站恢复正常访问。

从这次经历里，我最终总结出几个经验。

第一，先跑通最短链路，不要一开始追求完美。

一开始我其实想做得很“高级”：版本目录、自动切换、可回滚、兼容 1Panel 都要一起上。结果越是这样，越容易踩环境差异坑。

更稳的做法是：

先做最短可用链路。
每一步都单独验证。
哪一步坏了就只查那一步。

第二，服务器“看到目录”不等于服务“能读取目录”。

宿主机上执行：

ls -l /opt/1panel/www/sites/calorie

看到一切正常，不代表 OpenResty 真能按同样路径读取。

以后碰到 1Panel、Docker、容器环境时，第一反应应该是：

我在 shell 里看到的路径，和服务进程看到的路径，是不是同一个？

第三，浏览器看到的页面，不一定是真实线上状态。

PWA、Service Worker、浏览器缓存都会让你误判。

以后如果怀疑“网站没更新”，应该先执行：

curl -I 域名

先看真实响应是 200、404 还是 500。如果浏览器还能打开，但 curl 是 500，那大概率就是缓存干扰了判断。

第四，相对路径软链接在这种场景下比绝对路径更稳。

这次问题最后其实就卡在一个很小的细节上：

绝对路径软链接：看上去明确，但跨宿主机和容器容易翻车。
相对路径软链接：在同一挂载目录下更稳。

这个坑看起来很小，但杀伤力非常大。

本章小结

跑通之后回看，CI/CD 的价值不只是自动上传文件，而是让发布过程中的每一步都有明确职责，也都有办法验证。

后续优化

虽然现在这套 CI/CD 已经能用了，但后面还有几件事可以继续优化。

1. 限制发布权限

比如：

给 main 分支加保护。
不允许随便直接 push。
至少减少误操作风险。

2. 不再直接用 `root` 做部署

这次为了尽快打通链路，部署用户直接用了 root。

长期来说，更稳妥的方式是：

单独建一个部署用户。
只给它必要权限。

3. 进一步处理 PWA 缓存更新体验

现在虽然项目已经有更新提示逻辑，但出了线上故障时，缓存也确实容易干扰判断。

后面还可以继续优化：

缓存更新策略。
强制刷新提示。
发布后的缓存验证方式。

本章小结

现在的链路已经可用，后续优化重点应该放在权限收敛、发布安全和缓存体验上，而不是继续堆复杂度。

总结

这次搭 CI/CD，表面上看只是“自动发布网站”，但实际踩到的问题非常真实：

CI 工具版本冲突。
1Panel 和系统 Nginx 的差异。
宿主机路径与容器路径不一致。
绝对路径软链接带来的隐藏问题。
PWA 缓存掩盖真实线上错误。

最后真正让我把这套流程搞通的，不是“多改几次试试看”，而是这几个排查习惯：

先确认哪一层成功了，哪一层失败了。
不拿浏览器现象当唯一依据。
用日志和真实 HTTP 返回来判断问题。
把环境差异搞清楚，而不是只看“目录在不在”。

现在回头看，这套 CI/CD 的价值不只是省掉手动上传，更重要的是：

它把发布过程变成了一个可重复、可验证、可排查的流程。

这才是自动化真正有意义的地方。

深入理解浏览器的事件循环与异步机制

Wed, 15 Apr 2026 00:00:00 GMT

深入探讨浏览器的进程模型、渲染主线程的运作方式以及 JavaScript 中的异步与事件循环机制，这对于前端开发者来说是不可或缺的底层知识。

浏览器的进程模型

浏览器是一个多进程、多线程的应用程序。进程与线程的关系是一对多。浏览器主要包含三个核心进程：

浏览器进程
网络进程
渲染进程（包含一个渲染主线程）

:::tip[面试高频 Q&A] Q: 为什么渲染进程不使用多个线程来处理任务（如操作 DOM）？ A:

DOM 线程不安全：多线程同时修改 DOM 会导致不可预知的问题。
锁的性能差：为了保证线程安全而引入锁机制，会大幅降低渲染性能。
JS 是单线程语言：这决定了其执行环境必须是单线程的。

:::

渲染主线程的工作原理

渲染主线程的生命周期可以概括为以下几个步骤：

无限循环：主线程开启一个不会结束的 for 循环。
获取任务：每次循环时，尝试从消息队列（任务队列）中取出一个任务执行。如果队列为空，主线程则进入休眠状态。
添加任务：其他线程在合适的时机将任务添加到消息队列的末尾，并唤醒处于休眠状态的主线程。

提示：任务本身没有优先级之分，但任务队列有优先级。在所有队列中，**微队列（Microtask Queue）**的优先级最高，必须优先调度执行。

深入理解 JavaScript 的异步与事件循环

:::tip[面试高频 Q&A] Q: 如何理解 JavaScript 的异步机制？ A: JavaScript 是一门单线程语言，运行在浏览器唯一的渲染主线程中。如果采用同步方式执行耗时操作，会直接阻塞页面的渲染和交互。为了避免这种情况，浏览器采用了异步机制。

具体运作过程如下：当发生诸如计时器（setTimeout）、网络请求或事件监听等耗时任务时，主线程会将这些任务交由其他相关线程去处理，自身则立即结束该任务的执行，转而继续执行后续的同步代码。当其他线程完成处理后，会将预先传递的回调函数包装成一个任务，加入到消息队列的末尾排队，等待主线程的调度执行。

在这种异步模式下，浏览器能够永不阻塞，从而最大程度地保证了单线程的流畅运行。 :::

:::tip[面试高频 Q&A] Q: 详细介绍一下浏览器的事件循环（Event Loop） A: 事件循环（或称消息循环）正是浏览器渲染主线程的核心工作方式。

在 Chrome 的浏览器源码实现中，正是通过开启一个无尽的 for 循环，不断从消息队列中取出首个任务执行。而其他线程只需将需要执行的回调任务追加至队列末尾。

过去，我们常把消息队列简单地分为“宏队列”和“微队列”。然而，随着浏览器环境的日益复杂，这种简单的二分法已不再适用，取而代之的是一种更加灵活、精细的调度方式。

根据 W3C 官方的解释：

每个任务都具有不同的类型。
同类型的任务必须放在同一个队列中。
不同类型的任务可以属于不同的队列。
不同的任务队列享有不同的优先级。

在每一次事件循环中，由浏览器自行决定从哪一个队列中取出任务执行。但是，浏览器必须包含一个微队列（Microtask Queue），并且微队列的任务始终具有最高的执行优先级，必须被优先调度和执行。 :::

小结

“单线程是异步产生的原因，事件循环则是异步的具体实现方式。”

理解这两者的关系与底层细节，是掌握 JavaScript 运行机制的重中之重。

深入理解浏览器的渲染原理

Wed, 15 Apr 2026 00:00:00 GMT

我很喜欢这句话：浏览器，是人类历史上计算机与科学技术领域最伟大的工艺品之一。在它背后，你能真切地感受到顶尖科学家是如何优雅地解决复杂问题的。

一句话摘要

本文详细解析了浏览器从收到 HTML 文档到最终在屏幕上绘制出页面的全过程，涵盖了渲染主线程与合成线程的协同工作机制。

浏览器的渲染流程

:::tip[面试高频 Q&A] Q: 浏览器是如何渲染页面的？ A: 当浏览器的网络线程收到 HTML 文档后，会产生一个渲染任务，并将其传递给渲染主线程的消息队列。在事件循环机制的作用下，渲染主线程取出消息队列中的渲染任务，开启渲染流程。

整个渲染流程分为多个阶段：HTML解析、样式计算、布局、分层、绘制、分块、光栅化、画。每个阶段都有明确的输入输出，上一个阶段的输出会成为下一个阶段的输入，形成了一套组织严密的生产流水线。 :::

渲染主线程的工作原理

渲染主线程负责将 HTML 转换为带样式的 DOM 树，并生成绘制指令。（阶段 1-5）

1. HTML 解析 (Parse HTML)

从字符串到 DOM 树与 CSSOM 树。

:::tip[面试高频 Q&A] Q: CSS 会不会阻塞 HTML 解析？JS 呢？ A:

CSS 不会阻塞 HTML 解析：如果主线程解析到 link 位置，此时外部的 CSS 文件还没有下载解析好，主线程不会等待，而是继续解析后续的 HTML。这是因为下载和解析 CSS 的工作是在预解析线程中进行的。这就是 CSS 不会阻塞 HTML 解析的根本原因。
JS 会阻塞 HTML 解析：如果主线程解析到 script 位置，会停止解析 HTML，转而等待 JS 文件下载好，并将全局代码解析执行完成后，才能继续解析 HTML。这是因为 JS 代码的执行过程可能会修改当前的 DOM 树，所以 DOM 树的生成必须暂停。这就是 JS 会阻塞 HTML 解析的根本原因。

:::

2. 样式计算 (Recalculate Style)

从 DOM 树变成带样式的 DOM 树。

遍历 DOM 树，依次为每个节点计算它的最终样式。在这一过程中，很多预设值会变成绝对值，比如 red 会变成 rgb(255,0,0)；相对单位会变成绝对单位（例如 em 会变成 px）。

3. 布局 (Layout)

带样式的 DOM 树变成布局树，计算元素的位置与几何信息。

4. 分层 (Layer)

产生图层。

主线程会使用一套复杂的策略对整个布局树进行分层。分层的好处在于，将来某一个层改变后，仅会对该层进行后续处理，从而提升效率。

5. 绘制 (Paint)

图层到指令集。

主线程会为每个层单独产生绘制指令集，用于描述这一层的内容该如何画出来。完成绘制后，主线程将每个图层的绘制信息提交给合成线程，此时渲染主线程的当前工作到此结束。

合成线程的工作原理

合成线程接手主线程的任务，将绘制指令转化为真实的像素并输出到屏幕。（阶段 6-8）

6. 分块 (Tiling)

图层到块。

合成线程首先对每个图层进行分块，将其划分为更多的小区域。它会从线程池中拿取多个线程来完成分块工作。

7. 光栅化 (Raster)

块变成位图。

光栅化在 GPU 里面进行，也会开启多个线程，将分好的块转化为实际的像素点（位图）。

8. 画 (Draw)

位图到指引（quad）。

合成线程计算出每个位图在屏幕上的位置，交给 GPU 进行最终呈现，transform 就在这里发生。

:::tip[面试高频 Q&A] Q: 为什么 transform 的效率高？ A: 因为 transform 既不会影响布局，也不会影响绘制指令，它影响的只是渲染流程的最后一个 Draw 阶段。由于 Draw 阶段在合成线程中执行，所以 transform 的变化几乎不会影响渲染主线程。反之，渲染主线程无论如何忙碌，也不会影响 transform 的变化。 :::

小结

“将复杂的网页渲染拆解为互相衔接的八个流水线步骤，这正是浏览器工程拆解能力的极致体现。”

通过主线程与合成线程的精妙配合，以及 GPU 的加速渲染，浏览器保障了页面加载时的正确解析，也赋予了页面后续动画与交互的高性能潜力。

从零手搓 AI 网页对话：原生流式传输技术实践总结

Tue, 31 Mar 2026 00:00:00 GMT

在当今的大模型应用开发中，“流式传输”几乎是提升用户体验的必修课。如果不使用流式，用户必须死死盯着 Loading 图标等待大模型把几百上千个字全部生成完毕，体验极差。

为了彻底搞懂流式请求的底层原理，我决定抛开现成的框架和高度封装的 SDK，使用纯粹的 HTML/原生 JS + Node.js (Express)，从零开始搭建了一套 AI 对话系统。以下是整个演进和学习过程的技术复盘。

1. 架构与选型：化繁为简

为了专注核心技术——“推流”与“接流”，系统被设计为最精简的三层结构：

前端：负责处理用户输入、发送 POST 请求，并“像打字机一样”把接到的碎片文本拼接在 DOM 节点上。
中间代理 (Node.js)：负责接收前端的诉求，向真实大模型发起请求，同时建立流式通道透传片段给前端。
大模型 API：接入符合业界标准的通用大模型服务端接口。

2. 避坑指南：为什么不用原生的 EventSource ？

:::warning 最开始查阅资料时，发现很多教程推荐使用原生提供的 new EventSource() 来实现 Server-Sent Events 流式接收。但在实际技术调研时，发现一个问题：EventSource 只支持 GET 请求。大模型对话需要把包含大量字符的 history (历史上下文数组) 传给后端，GET 请求的 URL 长度限制会成为致命短板。 :::

最终方案：采用 Fetch API + POST 请求 + 流式拦截。

3. 后端如何“造流”？

为了不被繁杂的网络环境和限流报错打断思路，最好的练习方式是先手搓一个本地 Mock 推流接口。普通的 HTTP 接口通常是把全部数据塞进变量最后一并发走。而流式接口的核心在于：

先告诉浏览器“我要持续发片段了”。
用 res.write() 不断推送细小的数据。
最后用 res.end() 收尾。

Node.js 发流示例：

app.post('/api/mock/chat/stream', (req, res) => {
    res.setHeader('Content-Type', 'text/event-stream; charset=utf-8');
    res.setHeader('Cache-Control', 'no-cache');
    res.setHeader('Connection', 'keep-alive');

    const chars = "这是一段用来测试流式打字机效果的 Mock 文本".split('');
    let currentIndex = 0;

    const timer = setInterval(() => {
        if (currentIndex < chars.length) {
            res.write(chars[currentIndex++]); 
        } else {
            clearInterval(timer);
            res.end(); // 告诉前端结束了
        }
    }, 50);
});

4. 前端读取与深层解析：解码与数据的“三连操作”

前端拿到了流，普通 fetch 会挂起直到 res.end()，我们需要通过 response.body.getReader() 打开“渐进式水管”，而此时我们拿到的实际上是包含底层字节编码的 Uint8Array（无符号整数数组）。此时我们引入了一个关键对象——TextDecoder 解码器。

让我们细致看看我们用于接收流的内部循环做了什么：

const reader = response.body.getReader();
const decoder = new TextDecoder('utf-8');

while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    
    const chunkText = decoder.decode(value, { stream: true });
    aiMessageDiv.textContent += chunkText;
}

:::note[解析一：TextDecoder 与 stream: true 的玄机] 在此处，每次调用 TextDecoder 的 decode 方法对 value 进行解码。此 value 即来自响应体的数据片段，比如底层数组若是 [100, 97, 116, 97] 四个数字合起来对应字符就是 'data'。所以 decode 是在把无符号整数数组映射为字符串。

特别需要注意 stream: true 参数，这对于流式传输极为重要，因为它专门用来处理多字节字符的残留问题。比如中文字符在 UTF-8 编码规则下需要用到三个数字（例如表示某些汉字需要 228, 189, 160）。由于流的数据是被硬生生一块块截断传输的，这段字节可能在两次接收之间“拦腰斩断”。如果不完整，TextDecoder 会直接解出乱码；而加上 stream: true 参数后，它会在内部将不完整的字节缓存起来，累积到下次凑齐完整数据后再进行解码，从而完美避免了中文乱码灾难。 :::

解析二：如何面对真实 API 的数据格式？

目前的代码里后端发什么我们就直接拼什么。但在真实 API 和标准 SSE 约定里，包含多行带有 data: 前缀的 JSON 字符串（例如 data: {"content":"你好"}），并且用空行分割，最后一行固定为 data: [DONE]。这时候在循环接到 chunkText 之后，我们就需要紧接着进行数据清洗的操作：

split('\n\n')：为什么按换行符分割呢？因为每次循环拿到的 value 一定包含一个或多个完整的 JSON 串区段。将多行响应片段分离出来备用。
filter & map：遍历判断是否是结束标识，将空行过滤，随后通过 map 去掉文本头部的 data: 前缀字符。
反序列化解析：最后转化为真正的 JS 对象（JSON.parse），提取出对象中的 content 字段去驱动 UI 显示。这里如果是在后端 Node.js 控制台打印流水的话，切记要使用 process.stdout.write 而不是 console.log，以免反复自动换行破坏连续阅读体验。当这一切循环结束后，我们就拿到了本轮对话的完整回复，后续逻辑便如寻常。

5. 进阶探讨：从循环驱动到 Async Generator (彻底解耦)

你可能发现了，这一段代码其实大部分都在做数据转换和格式处理的事情，这在应用设计上会暴露出一个问题：数据处理逻辑（解码、split、格式清洗）和业务逻辑（更新到 DOM 气泡）深深地耦合在一起。假设项目中有很多地方都需要进行这样的异步迭代（比如要复用流读取做分析、打点），如何避免重复代码？能否只在循环里保留核心业务代码，把相对通用的逻辑封装到专门的方法内部？这里我们要了解流背后的——迭代器（Iterator）和生成器（Generator）。

理解迭代的本质：同步 vs 异步迭代器

ES6 同步迭代 (for...of)：规范规定了实现了 Symbol.iterator 方法的对象都可以用 for...of 进行遍历。我们常用的原生数组由于内置了该对象便具备了这个特性。实际上如果拆开来看，在这个 iterator 对象上有三个方法，重点关注 next()，每次调用都会同步返回下个值以及是否结束 return { value, done }。for...of 就是我们在底层帮我们简化驱动这种对象的语法。
```
// 同步迭代示例
const arr = [1, 2, 3];
const iterator = arr[Symbol.iterator]();
console.log(iterator.next()); // { value: 1, done: false }
console.log(iterator.next()); // { value: 2, done: false }
console.log(iterator.next()); // { value: 3, done: false }
console.log(iterator.next()); // { value: undefined, done: true }
```

ES9 异步迭代 (for await...of)：规范规定了实现 Symbol.asyncIterator 方法的对象适用。像 Fetch API 请求返回的 ReadableStream 恰恰便实现了这个接口！同样去驱动它，不同的是这里的 next() 方法返回的是一个需要 await 的 Promise（包裹着和同步迭代一样的 { value, done }）。

// 异步迭代简易示例（模拟）
const asyncIterable = {
  [Symbol.asyncIterator]() {
    let i = 0;
    return {
      next: async () => {
        await new Promise(resolve => setTimeout(resolve, 100)); // 模拟异步延迟
        if (i < 3) return { value: ++i, done: false };
        return { value: undefined, done: true };
      }
    };
  }
};

// 使用 for await...of 消费
(async () => {
  for await (const val of asyncIterable) {
    console.log(val); // 依次输出 1, 2, 3 (每隔100ms)
  }
})();

引入异步生成器解耦

所以，最优雅的设计，是编写一个异步生成器函数 (Async Generator)，利用 yield 将复杂的网络流转变为业务所需的“纯净流”：

/* 
 注意到 async function 后面多了一个星号 *，这表示它是一个异步生成器函数。
 在函数内部使用 yield 关键字产出一个值，并暂停函数执行。
*/
async function* processStream(response) {
    const reader = response.body.getReader();
    const decoder = new TextDecoder('utf-8');

    while (true) {
        const { done, value } = await reader.read();
        if (done) break;
        
        // 解析二进制
        const chunkText = decoder.decode(value, { stream: true });
        // (此处省略上方讲到的 split、map、filter 及去 data: 和 parse 的数据处理过程)
        const cleanContent = "...(提取好的业务字符串)...";
        
        // 使用 yield 产出最终给到业务层食用的值
        yield cleanContent; 
    }
}

很多人学了语法但觉得"生成器好像没什么用”，实际上它其中一个极具价值的作用便在于流的转换！调用生成器函数会返回一个自动实现了可迭代接口的新对象。这样我们就把 fetch 丢出来的晦涩难懂的 readableStream 转换成了自定义的流形态，完美屏蔽了内部数据格式处理细节。

经过这身定制封装，在 UI 侧的业务代码就会变得清爽无比，只需要使用极为现代的 for await...of：

// 业务层视角：代码极致干净，只聚焦渲染处理自身关心的字符串
for await (const pureText of processStream(response)) {
    aiMessageDiv.textContent += pureText;
}

6. 收获与总结

在本次探索中，不仅从最底层的机制打通了 AI 对话项目从无到有的流式实践，更通过深挖背后的网络与语言特性，我们发现：

流的断裂容错：一个小小的 { stream: true }，巧夺天工地避免了底层基于包截断带来的错位乱码陷阱。
三段式拆解：理解了真实场景下面对 data: xxx 的 split, filter, map 拆解机制。
现代 JS 语法的优雅：从繁琐的 reader.read() 发动机模型，通过 async function* (生成器) 和 for await...of 的绝妙化学反应，优雅地完成了底层与业务的隔离。在 AI 开发中，往往前端不会直接去处理底层数据结构，我们要学会通过“流转换”为业务自定义的数据结构。

这是一次对 HTTP 流通信机制与 ES9 前沿迭代语法结合的深刻实践。感谢你看到这里，希望这篇文章能带给你启发！

AI 名词总结：从 LLM 到 agent 的概念地图

Tue, 24 Mar 2026 00:00:00 GMT

一句话摘要

多数 AI 名词并非全新发明，而是围绕同一个目标逐层抽象出来的工程产物：让模型更可控，让系统更好用，让普通人更容易上手。

一切的起点：LLM

大语言模型（LLM），本质是“语义匹配”，是在上下文里预测下一个 token。它通过海量文本训练，学习语义关联，再根据输入给出概率上更合理的输出。

但 LLM 天生只会“说”，不会“做”。为了让它在对话中更稳定，第一层工程包装自然出现：

prompt：你给模型的任务指令；
context：补充给模型的背景信息和约束；
memory：把历史对话压缩后再注入，减少跑偏和遗忘。

这些词有明确的工程目标：让多轮对话可持续、可复用、可控制。LLM、prompt、context、memory 是第一层名词，解决的是“怎么让对话可持续、可复用、可控制”。

本章小结

LLM 提供了语言能力底座，而 prompt、context、memory 是让这套能力可持续使用的第一层工程手段。

从会说到会做：agent 与外部知识

当你希望模型查网页、读本地文件、调用数据库或运行脚本时，问题就从“会不会说”变成了“会不会做”。模型本身不会直接执行动作，于是出现了中间层：agent。

agent 可以理解为调度器：它把模型意图翻译为工具调用，再把工具结果返回给模型继续推理。

这一层又带来了新名词，比如获取网络信息的 Web Search、获取本地知识库的 RAG（检索增强生成）。它们共同做的是把“模型参数外的信息”接进系统，提升答案的新鲜度和可靠性。agent、RAG 是第二层名词，旨在解决“让模型接入外部世界”的问题。

本章小结

当目标从“会说”升级到“会做”，agent 与 RAG 的价值就在于把模型接到真实世界的数据和动作上。

协议层：function calling 与 MCP

function calling 是模型与 agent 之间的约定，目标是让模型用结构化格式表达“我要调哪个工具、传什么参数”。它解决的是“模型怎么把意图说清楚”。

MCP 是 agent 与工具服务之间的约定，目标是标准化工具发现、参数传递与结果返回。它解决的是“系统怎么把这件事真正做出来”。

:::important[不要混淆两层协议] function calling 面向模型输出格式，MCP 面向工具服务协议。两者互补，不互相替代。 :::

此时的 agent 像一个传话与调度中枢：接收模型意图，执行工具调用，再把结果回传给模型和用户。

agent 与用户之间的交互形态也越来越多样，虽然底层交互方式还是文字，但表现形式有很多：

命令行（CLI）：Claude Code、Codex、OpenCode；
编程 IDE：Cursor、Trae、Antigravity；
桌面助手：如 ClawBot（最近爆火的龙虾）

本章小结

function calling 负责“说清楚要做什么”，MCP 负责“把事情标准化做出来”，两者合起来才是完整调用链。

能力封装：workflow、skill 与 agentic AI

当你反复让 AI 做同类任务时，第一反应通常是把流程固化成脚本：

编程方式：LangChain；
低代码方式：workflow。

但固定流程在输入输出变化较大时会变得僵硬。于是会出现一个“能力目录”：把不同脚本和规则打包成可复用单元，让 agent 在执行前按需加载，这就是 skill 的价值。

从自动化能力的谱系看，大致可以这样理解：

LangChain：偏硬编码，稳定但灵活性最低。
workflow：流程模块化，修改更快，但仍依赖预设路径。
skill：把流程规则沉淀为能力包，让 agent 按任务调用。
agent：在循环中动态决策、调用工具，并判断完成度。

这本质上是从 workflow 范式逐渐向 agentic AI 范式的转变。workflow 预先将节点串联，编排好完成一件事的具体流程，并在节点中调用大模型来完成一部分需要智能的任务。这需要“n 份提示词 + 手动工具调用 + n 个 if-else”，更像是一种自动化而非智能化。相反，agentic AI 则充分发挥模型的推理能力，让 AI 在任务循环中自主决策、使用工具，并判断任务的完成度。它只需要“1 份提示词 + 自动工具调用 + 1 个循环”。

workflow 与 skill 解决的是复用效率，agentic AI 解决的是动态决策能力。

本章小结

workflow 与 skill 优化的是复用效率，而 agentic AI 真正放大的，是任务执行中的动态决策能力。

我的判断：无配置可用才是终局

MCP、skill、桌面助手等被过度炒作的概念，很多时候只是技术演化中的中间产物。褪去包装后，它们仍然围绕同一件事：减少用户与模型沟通成本，把该自动化的部分自动化。

从产品演化看，谁能降低上手门槛，谁就更容易获得规模化用户。普通用户不会长期为“术语先进”买单，而会为“能直接用、够稳定、性价比高”买单。以近期走红的工具为例，关键往往不是概念更新，而是连接能力、定时能力和可视化管理能力做得足够完整。

token 成本今天仍是约束，但如果推理成本继续下降，系统设计重心会进一步转向体验与可靠性，而不是手工拼装中间层概念。未来更可能胜出的，是“打包完成”的 agent 产品：常用能力内置，复杂协议隐藏，交互尽量自然。下一阶段的竞争焦点不是术语数量，而是无配置可用的产品完成度。

本章小结

从用户侧看，真正可持续的竞争力不是新名词，而是“几乎零配置就能稳定完成任务”的产品体验。

总结

从 LLM 到 agent，从 function calling 到 MCP，从 workflow 到 skill，本质都在回答同一个问题：如何在可控与灵活之间，用更低成本交付可用能力。

把这些词看成“能力分层”而不是“流行标签”，讨论会更清晰：先看需求，再谈架构。

AI 工作流总结：从“写代码”到“管系统”

Sat, 21 Mar 2026 00:00:00 GMT

一句话摘要

在 AI 编程时代，个人生产力上限正在被抬高。真正的核心竞争力不再只是“写得快”，而是能否通过文档、计划和测试，把不确定的 agent 行为约束为可复用、可验证、可迭代的工程流程。

1. 文档主导工作流

适用场景：需求复杂、影响范围大、多人协作、需要可追溯决策过程的项目。

流程步骤

发散需求让 AI 讨论和挑刺、做头脑风暴、调研同类产品。这一阶段不急着落代码，只处理业务目标、边界与优先级。
写 PRD（核心项目资产） PRD 最少包含：
- 术语表：统一项目语义，避免沟通歧义。
- 交互方式：明确关键交互路径和用户反馈。
- 验收标准/边界定义：为后续测试与回归提供锚点。
plan + review 先基于 PRD 生成计划，再进行多轮 review，确保任务拆分可执行、可验收。
实现进入编码阶段。这里强烈推荐配合 worktree 并行推进正交任务，减少上下文切换损耗。
功能测试 + 迭代如果出现偏差，优先回到文档检查“定义是否正确”，而不是只在代码层补丁式修复。
人工 review 对业务一致性、架构风险、测试覆盖进行最终兜底。

小结

文档主导的本质是：先把“为什么做、做到什么算完成”说清，再让 AI 高速执行“怎么做”。

2. 原型主导工作流

适用场景：需求模糊、体量较小、需要快速看效果的任务。

流程步骤

AI 快速开发原型
按反馈快速迭代
通过代码反向生成文档
转入文档主导流程，进入规范化开发

小结

原型主导更像“先看样子再收敛定义”，文档主导更像“先定规则再规模化执行”。两者不是对立关系，而是前后衔接关系。

3. 零散的实践结论

3.1 显式要求 agent 采用 TDD

TDD 对 agent 的价值非常直接：

每轮目标更小，agent 不容易“脑补过度”。
测试先行，需求变成可执行文档。
代码改动引入回归时更容易第一时间暴露。
你始终知道“现在为什么改、改完是否正确”。

3.2 文档生命周期：用后即弃 vs 持续维护

二者都可以成立，但在长期项目中，持续维护文档的收益更高。

为什么持续维护文档重要

1 角色升级

业务需求 > 技术实现。工程师需要逐步从“执行者”升级为“方向与质量的监管者”。在现阶段，agent 的自主性与长期记忆仍无法替代人类，因此你仍需理解项目深度。

2 带宽扩大

生产力提升后，单人可管理的项目规模和数量都会增加。为了降低记忆与沟通成本，必须提升抽象层级，从代码视角转向文档视角。

虽然会损失部分细节，但能保留核心骨架，且维护成本通常更低。在 agent 协助下，文档到代码的转换成本持续下降，自然语言与代码实现之间的边界会越来越模糊。

长期看，工程师会更多关注架构与行为逻辑，而不是把时间消耗在语法细节上。在 agent 解决长期记忆和主动性问题之前，维护高质量文档仍是阶段性的最佳实践。

3.3 其他操作建议

计划先行（plan）
让 agent 写测试
善用 skill 把固定手动流程脚本化，例如：改完自动编译、跑测试、读日志，减少重复劳动和上下文切换。
关注骨架而非细节
工具轻量化
明确工作流应用场景

小结

在 AI 时代，稳定产出的关键不是让 agent 一次写对所有代码，而是让计划、测试、文档和工具链形成闭环。这样才能在规模上升时保持质量与节奏。

4. 总结

对于大规模、定义明确的 feature，我们以文档为核心主导开发。

对于重要且容易描述的 feature，我们持续维护文档，把文档作为长期资产。

对于其他 feature，我们按成本和收益灵活选择策略：

当 feature 较小，或定义仍不清晰时，以原型开发为核心，快速试错与迭代。
当小 feature 逐步演化为定义明确的大 feature 时，再切回文档主导流程，对其进行系统化重构与治理。

解决跨域问题

Thu, 12 Mar 2026 00:00:00 GMT

一句话摘要

Apifox 能通不代表浏览器能通；跨域问题的第一检查点应该是预检请求 OPTIONS，不是业务接口参数。

问题现场

我最开始被“Apifox 已经测通”误导了，默认认为后端接口没问题。
但浏览器联调时登录请求始终失败，进一步看 Network 才发现真实请求前的 OPTIONS 预检直接返回了 405 Method Not Allowed。

本章小结

“接口通了”必须明确是哪个运行环境通了，测试工具和浏览器是两套约束体系。

关键认知

CORS 预检是浏览器行为，不是后端业务逻辑本身：浏览器在非简单请求前会发 OPTIONS 探路，后端必须返回正确的 Access-Control-Allow-* 响应头。
Apifox 不受同源策略约束：它发的是裸 HTTP 请求，因此无法覆盖浏览器端的 CORS 问题。
排查顺序要前移到 Network：先看有无 OPTIONS、状态码和响应头，再看业务参数。

本章小结

跨域问题要先确认“请求是否被浏览器放行”，再谈“业务接口是否正确”。

方案取舍

我评估了两条路径：

方案 A：后端加 CORS（治根）
优点是长期干净；缺点是依赖后端团队排期。
方案 B：前端走 BFF 代理（快速落地）
浏览器请求同源 /api/*，由 Next.js 服务端转发到真实后端，能立即绕开 CORS 阻塞。

这次我采用 BFF，因为当前阶段单人推进前端，跨团队沟通成本高，先保证业务联调闭环更务实。

本章小结

治根和治标不是对立关系，关键看当前交付目标和协作成本。

本章小结

从“无法登录”到“方案落地”，这次排障已经形成了可复用的 checklist。

总结

这次最大的收获不是修了一个 bug，而是校准了排障方法论：
先看浏览器链路，再看业务逻辑；先保证可交付，再逐步推进根治方案。后续项目里，我会默认把 CORS 预检检查纳入联调首步。

SSR 与 CSR 在 Next.js 中的实践要点

Sun, 18 Jan 2026 00:00:00 GMT

一句话摘要

这次整理让我更清楚地理解了 Next.js 的核心权衡：SSR 负责“快看到”，Hydration 负责“能交互”，而响应式冲突要优先用 CSS 方案规避。

背景与问题

在 Next.js（App Router）里，我最初的问题是：页面明明 SSR 首屏很快，但一涉及交互或响应式判断就容易出现 Hydration 警告，甚至内容闪动。

核心难点不是“会不会写组件”，而是“服务端和客户端的首次输出是否一致”。

本章小结

SSR 场景下，渲染一致性是第一原则，交互能力是第二步再补。

核心概念

在 Next.js 里，组件分为 Server Component 和 Client Component：

Server Component（默认）：
- 运行在服务端。
- 不可使用 React Hooks、事件监听、浏览器 API。
- 优点是减少客户端 bundle，首屏更轻。
Client Component（"use client";）：
- 需要 Hydration 后才具备完整交互。
- 可使用状态、事件和浏览器能力。
- 适合表单、按钮、动态交互区域。

最佳实践是“叶子节点 client 化”：页面尽量保持 server，只有必须交互的局部切到 client。

本章小结

组件边界划分正确，能同时拿到首屏性能和交互能力。

Hydration 机制

Hydration 可以理解为“把交互能力重新附着到已渲染的 HTML 上”。

过程是：服务端先输出静态内容，客户端下载 JS 后再绑定事件和状态。
所以 SSR 的优势是内容先到，挑战是交互稍后到。

这也是为什么 SSR 通常改善 FCP，但仍可能出现 TTI 体感延迟。Next.js 的 streaming 和选择性 hydration 就是在缓解这个落差。

本章小结

SSR 不是“全都更快”，而是“先可见，再可交互”，设计时要管理好用户预期。

SSR 下的响应式实践

常见 Hydration mismatch 报错本质是：服务端首次 HTML 与客户端首次渲染不一致。

典型误区是直接在渲染阶段读取 window.innerWidth 并分支输出不同组件。
在 SSR 场景下更稳妥的做法是优先用 CSS 媒体查询（或 Tailwind 断点类）处理展示差异，让初始 HTML 保持一致。

return (
  <>
    <div className="block md:hidden">
      <MobileNav />
    </div>
    <div className="hidden md:block">
      <DesktopNav />
    </div>
  </>
);

本章小结

响应式优先交给 CSS，能显著降低 mismatch 风险并提升渲染稳定性。

总结

这次整理后，我对 SSR 的判断更清晰了：
先保证首屏输出一致，再局部增强交互；先用 CSS 解决响应式，再用 JS 处理必须的行为逻辑。这样才能把 Next.js 的性能优势稳定地发挥出来。

小程序真机图片失效与 OSS 防盗链排查

Fri, 16 Jan 2026 00:00:00 GMT

核心表现摘要

这次真机故障的根因不是代码，而是 OSS 防盗链白名单缺失 servicewechat.com，导致“开发者工具可见、真机不可见”的假象。

问题现场

现象非常典型：开发者工具里图片正常，真机上图片全白。因为工具里看起来一切正常，我一度把排查方向放在代码和资源本身上。

本章小结

“工具正常、真机异常”通常不是偶发 bug，而是环境差异触发了同一配置的不同路径。

根因拆解

今天最大的认知变化是重新理解 OSS 防盗链逻辑：

浏览器常见空 Referer 请求，命中“允许空 Referer”时可以访问资源。
微信真机会带 servicewechat.com Referer。
白名单没有该域名时，OSS 会直接返回 403。

结论：Allow Empty Referer 并不等于“完全公开”，它只是放行“没报来源”的请求。

本章小结

这不是“真机玄学”，而是 Referer 白名单策略的必然结果。

排查中的干扰项

中间还有一个干扰项：电脑浏览器也打不开资源，误导我以为 OSS 文件有问题。最后确认是本地代理影响了 DNS 或 IP 路由。

经验是：排查这种网络问题时，手机 4G/5G 环境往往比本机浏览器更干净，更适合作为对照组。

本章小结

先区分“平台策略问题”和“本地网络问题”，能显著缩短排障路径。

本章小结

后续动作已经明确：先修配置，再做代码与文档收口，避免团队重复踩坑。

总结

这次故障让我重新建立了一个排查顺序：先看请求环境差异，再看平台策略，最后才是代码本身。真机问题并不可怕，可怕的是拿错对照组和排查优先级。

富文本样式不生效排查总结

Thu, 15 Jan 2026 00:00:00 GMT

一句话摘要

这次排查确认了一个关键点：在小程序富文本场景里，单靠 scoped + CSS 穿透不稳定，tag-style 才是可控且跨端一致的方案。

背景与现象

在 .rich-text-content 里写了自定义样式，但运行后看起来“加不加样式都一样”，富文本区域没有被影响。

本章小结

问题表面是“样式不生效”，本质是样式作用域和渲染路径不一致。

根因分析

页面里使用了 <style lang="scss" scoped>，scoped 样式默认无法作用到子组件内部渲染出来的真实节点。
uv-parse 的富文本最终由内部组件渲染（如 node.vue / rich-text），外层容器 .rich-text-content 的 CSS 只会影响容器本身，不会自然影响到内部的 p / span / img 等元素。
即使尝试 :deep(.uv-parse)，也可能仍不生效：
- uv-parse 内部会用带下划线前缀的类名（如 ._p、._h1），不是直接的 p/h1 标签样式。
- 小程序端不少内容走原生 rich-text 渲染，CSS 穿透对原生组件经常不稳定或失效。

本章小结

只靠样式穿透，风险点多且难以预测，尤其在小程序端更容易出现“本地可用、真机失效”。

方案对比与选择

方案 A：用 ::v-deep / /deep/ / >>> 做样式穿透（改动小，但端上不一定稳定，且要对准 uv-parse 内部类名）。
方案 B：用 uv-parse 的 container-style 传入容器内联样式（适合改整体容器）。
方案 C（最终推荐）：用 uv-parse 的 tag-style 给特定标签注入内联样式（最稳定、影响面最小）。

最终推荐 tag-style：解析时把样式直接写到节点上，不依赖 CSS 穿透。

优点：

样式直接注入到 HTML 节点，优先级高
只影响当前这个 uv-parse 实例（不会污染全局）
小程序/H5/App 兼容性更好

本章小结

在“可维护性 + 跨端稳定性”维度上，tag-style 是当前最小代价、最高确定性的方案。

落地计划

修改 detail.vue：

在 data() 增加 parseTagStyle（为 p/img/h1... 等标签定义内联样式）
在 <uv-parse> 上绑定 :tag-style="parseTagStyle"

本章小结

改动点集中在单一页面，影响面可控，回归成本低。

总结

这次排查再次说明：富文本问题往往不是“CSS 写错了”，而是“渲染边界没看清”。以后遇到类似问题，我会优先确认渲染链路，再决定是用样式穿透还是组件能力。

别再为了大而全的技术选型自我消耗

Fri, 09 Jan 2026 00:00:00 GMT

核心观点摘要

这次复盘让我确认了一件事：在内容消费场景里，技术选型的第一原则不是“功能最全”，而是“是否刚好满足业务并可长期维护”。

背景与问题

我之前陷入了典型的“工程师思维陷阱”：总想选一个能力最全、可扩展性最高的富文本方案，担心“只展示不编辑”显得技术含量不够。

但回到业务本身，我当前做的是内容分发，不是内容生产。前端核心任务是稳定渲染与性能保障，而不是把后台编辑器能力搬到小程序端。

本章小结

问题不在技术能力不够，而在于目标错位：把消费端当成生产端来设计了。

关键思路

拆分“编辑”和“显示”职责：编辑器服务后台管理系统，消费端只需要高性能渲染器。
前置约束，减少背锅：和后端提前约定 HTML 标签白名单（如 p、img、video），避免脏数据进入客户端。
入口统一容错：在渲染入口做一次标准化处理（如 max-width: 100%、空数据兜底），提升整体稳定性。
关注真实业务门槛：网课场景真正难点在长视频播放体验，例如检查点、HLS、弱网策略，而不是“编辑器功能比拼”。

本章小结

技术选型要先回答“业务到底需要什么”，再谈“技术还能做什么”。

本章小结

下一步不追求“大改架构”，而是优先把规约、容错和性能三件事做到可执行、可复用。

总结

这次最大的收获不是学了新框架，而是建立了判断标准：业务驱动技术，复杂度服务目标。把 uv-parse 这类现有工具用到稳定、可维护，就是当下最有价值的工程成长。

实习第一天：uni-app 学习笔记

Tue, 30 Dec 2025 00:00:00 GMT

面向实际业务的 uni-app 技术准备与性能优化考量

本次结合业务线技术栈（Vue 与 uni-app），整理对跨端框架的设计概念（如 nvue、nts、webview、weex），逻辑层与渲染层分离模型的理解，以及在遇到如大量视频与长列表等性能敏感场景下的解决方案调研。

开发侧的核心技术抓手

面对一套包含多端特性的新框架，首先应该建立快速交付抓手，不需要初期通读所有 API，优先把以下核心概念闭环：

项目结构：约定目录与文件构建原则及生命周期。
页面与组件：如何划分边界并组织基础的交互响应。
数据绑定：状态流转以及数据渲染双向机制。
事件处理：触控与端能力的 API 调用。
路由与跳转：App/页面级路由栈和跳转机制。
生命周期：不同端下的页面与组件初始化释放时机。
条件编译：多平台架构中最关键的跨端差异填平语法。

场景难点与技术预研

当前负责的业务存在大量较重的流媒体播放和列表交互需求，主要存在两个渲染及加载难点：

视频资源过大、不能强依赖一次性全量加载并造成网络与设备负担；
长列表的内存泄漏风险和前端 DOM（如小程序节点）上限的性能阻塞。

经过技术调研，制定初步技术解法如下：

视频方面：性能优化方案

针对网课视频时长大（半小时至数小时）的特点，不能采用全量下载。经过调研，制定了分阶段的优化方案。

1. 核心技术原理

HTTP Range Requests (范围请求)：这是“边下边播”和“拖拽进度”的基石。播放器通过 Range: bytes=start-end 请求头，只请求视频的特定片段，而非下载整个文件。
H.264 编码：兼容性最好的视频编码格式，确保在各种设备上利用硬件解码，省电且流畅。

2. 实施路线图

第一阶段：短期快速优化（前端主导）

启用 Range 请求：
- 确认 OSS 或后端接口支持 Range 请求头（返回 206 状态码）。主流 OSS（阿里云、腾讯云）默认支持。
- 前端 <video> 组件直接使用链接，会自动发送 Range 请求。
智能预加载：
- 列表页：静默预加载下一节课的元数据（时长、大小）或首个分片（前 1-2MB），利用 uni.downloadFile 或 XHR。
- 详情页：onLoad 时立即请求视频地址并初始化播放器，设置 preload="auto"。
体验优化：
- 利用 initial-time 实现断点续播。
- 监控下载速率，若持续低于码率则提示用户切换清晰度（如果有多清晰度源）。

第二阶段：长期架构升级（服务端主导）

HLS 流媒体：
- 将原始 MP4 转码为 HLS (.m3u8 + .ts) 格式。
- 切片：将大文件切成小的 .ts 文件，秒开速度更快。
- 多码率适配：生成不同清晰度（1080p, 720p, 480p）的流，播放器根据网络状况提醒用户切换,如果开了自动则自动切换（Adaptive Bitrate Streaming）。
CDN 加速：配合 CDN 分发切片文件，降低延迟。

3. 决策建议

立即行动：检查现有视频文件是否为 H.264 编码的 MP4。
- 如果是：直接上 Range 请求 + 预加载方案。
- 如果不是：优先转码为 H.264。
后续规划：随着用户量增长，搭建服务端转码服务，向 HLS 方案迁移。

列表方面：虚拟列表 vs 懒加载

懒加载（Lazy Loading）

本质：数据层按需加载（例如先加载前 20 条，滚动到底再加载下 20 条）；
问题：虽然减少了初始请求，但最终仍可能渲染大量 DOM 元素，导致页面卡顿。

虚拟列表（Virtual List）

本质：渲染层优化的进阶方案，只渲染可视区域内的少量 DOM 元素；
核心：通过占位容器模拟总高度，滚动时回收离开可视区域的 DOM，用它们渲染新进入可视区域的数据；
关键技术点：
- 计算每个项目高度（固定或动态）；
- 根据滚动位置计算显示范围（startIndex、endIndex）；
- 使用偏移（例如 transform: translateY(...)）来模拟正确位置。

全栈进阶：手撸核心业务逻辑

Wed, 10 Dec 2025 00:00:00 GMT

核心思考：理清前后端边界与状态流转

从纯粹依赖外部代码片段提示，走向自主重构与组件设计，对 Prisma 数据建模、前端 Pinia 状态管理以及路由架构有了更深的认知。

路由的物理与逻辑边界：从功能定位上理清了前端与后端路由的职责：
- 前端路由 (Vue Router)：控制视图层展现。基于 HTML5 History API 拦截 URL 变化并映射至对应视图组件，规避了全局重载。
- 后端路由 (Express Router)：控制资源与数据分发。遵循 RESTful 或其他规范对应至特定的业务逻辑/ Controller。两者的解耦是现代前后端分离协作的地基。
单一数据源 (Single Source of Truth)：在重构跨路由媒体播放器状态（播放、暂停、进度）过程中，再次印证了状态集约化管理的收效。
- 散列化反模式：视图容器、Audio 实例本身以及 LocalStorage 互相监听同步，将不可逆地引发状态撕裂和循环依赖。
- 集约化正解：Pinia 承担绝对且唯一的状态代理（大脑），播放器组件仅执行响应，LocalStorage 负责挂载/卸载时的数据快照。所有变更一律流经 Store 声明的 Action 函数。

核心功能重构与实现路径解析

1. 全栈开发流程 (Prisma + Express + Vue)

场景：实现一个“用户列表”功能。

Step 1: 数据建模 (后端) 在 schema.prisma 定义模型，这是数据的源头。
```
model User {
  id       Int    @id @default(autoincrement())
  username String @unique
  role     String @default("user")
}
```
执行 npx prisma db push 同步数据库。

Step 2: 接口开发 (后端) 在 userController.ts 中写逻辑，在 index.ts 注册路由。

// controller
export const getUsers = async (req, res) => {
  const users = await prisma.user.findMany();
  res.json(users);
};
// router
app.get('/api/users', getUsers);

Step 3: 状态管理 (前端) 在 stores/user.ts 定义 Store。

export const useUserStore = defineStore('user', () => {
  const userList = ref([]);
  const fetchUsers = async () => {
    const res = await fetch('/api/users');
    userList.value = await res.json();
  };
  return { userList, fetchUsers };
});

Step 4: 视图渲染 (前端) 组件三部曲：Store -> Action -> Template。

<script setup>
const userStore = useUserStore();
onMounted(() => userStore.fetchUsers());
</script>
<template>
  <div v-for="user in userStore.userList" :key="user.id">{{ user.username }}</div>
</template>

2. 播放器状态持久化 (Pinia + LocalStorage)

场景：刷新页面后，歌曲能接着上次的进度播放。

核心逻辑：
1. 存：监听切歌 (watch) 和页面关闭 (beforeunload)，将 currentSong 和 currentTime 存入 localStorage。
2. 取：Store 初始化时 (restoreState) 读取 localStorage。
3. 同步：利用 <audio> 的 loadedmetadata 事件，在音频元数据加载完成后，立即设置 currentTime。

关键代码 (Store)：

// 保存状态
const saveState = () => {
  localStorage.setItem('player-state', JSON.stringify({
    song: currentSong.value,
    time: currentTime.value
  }));
};

// 恢复状态
const restoreState = () => {
  const saved = localStorage.getItem('player-state');
  if (saved) {
    const { song, time } = JSON.parse(saved);
    currentSong.value = song;
    currentTime.value = time; // 恢复进度变量
  }
};

// 自动保存策略
watch(currentSong, saveState); // 切歌存
window.addEventListener('beforeunload', saveState); // 关窗存
restoreState(); // 启动取

关键代码 (组件)：

<audio
  ref="audioRef"
  @timeupdate="(e) => playerStore.currentTime = e.target.currentTime" <!-- DOM -> Store -->
  @loadedmetadata="audioRef.currentTime = playerStore.currentTime"    <!-- Store -> DOM (断点续传) -->
></audio>

3. 每日推荐 (前端算法 + 缓存)

场景：每天展示 10 首随机歌曲，当天刷新不变，第二天自动刷新。

实现原理：
1. 检查缓存：对比 localStorage 里的日期和今天是否一致。
2. 一致：直接用缓存里的 ID 列表去 Store 里找歌。
3. 不一致：执行洗牌算法，生成新列表，存入缓存。

关键代码：

const generateDailyRecommend = () => {
  const today = dayjs().format('YYYY-MM-DD');
  const cachedDate = localStorage.getItem('daily_date');

  if (cachedDate !== today) {
    // 洗牌算法：随机排序后取前10
    const randomSongs = [...songList.value]
      .sort(() => 0.5 - Math.random())
      .slice(0, 10);

    // 更新缓存
    localStorage.setItem('daily_date', today);
    localStorage.setItem('daily_ids', JSON.stringify(randomSongs.map(s => s.id)));
    recommendSongs.value = randomSongs;
  } else {
    // 走缓存逻辑...
  }
};

4. 全局播放器架构 (Layout 提升)

场景：切换路由（如从首页进专辑页），音乐不中断。

问题根因：原结构中，播放器组件 (AppFooterPlayerBar) 放在各个页面 (HomeView) 内部。路由切换会导致页面销毁 -> 播放器销毁 -> 音乐停止。
解决方案：将播放器提升到 App.vue 或全局 Layout 中，包裹 RouterView。

架构变更：

<!-- App.vue (新结构) -->
<template>
  <BasicLayout>
    <!-- 播放器在这里，永远不销毁 -->
    <RouterView /> <!-- 只有这里的内容在变 -->
  </BasicLayout>
</template>

总结

阶段性的重构充分说明，“能够跑通”只满足工程阶段其一，组件树和全局状态树从一开始的合理化设计，对后续重构调试的增益要远远大于补丁代码产生的心智消耗。

全栈第一步：前后端打通

Mon, 08 Dec 2025 00:00:00 GMT

核心思考

全栈的本质是“数据流转”：从宏观架构来看，后端工程相当于承担着“数据总线”与“管理中枢”的角色。
- 数据库 (SQLite)：数据持久化下层，承载存储职责。
- Prisma：ORM 工具，负责数据映射与数据库交互。
- Express：网关或控制层，处理 HTTP 请求与数据分发。
- 前端 (Vue)：视图层，获取 JSON 序列化数据并渲染为客户端 UI。打通全链路后，技术栈从单一孤岛合并成了数据流闭环。
TypeScript 的约束一致性：当前后端均切入 TypeScript 体系后，类型定义能够实现复用。在服务端定义的数据模型（如结构体），能够让前端在进行网络请求处理时直接做类型推断，极大降低了沟通成本与调试阻力。

知识内化（技术栈复盘）

🛠️ 后端基架 (Node + Express + TS)

从零搭建了一个标准的 TS 后端项目：

环境配置：npm init 起手，装 express、cors、dotenv 三件套。
TS 加持：配置 tsconfig.json，用 ts-node 直接运行 TS 代码，配合 nodemon 实现热更新（改一行代码，服务自动重启，不用手动切终端）。
ORM 神器 (Prisma)：
- 不用写 SQL 语句，直接定义 schema.prisma 模型。
- npx prisma db push 一键同步数据库结构。
- 写了个 seed.ts 脚本，一键注入测试数据，再也不用手动插数据了。

🔗 前后端通信 (The Bridge)

跨域 (CORS) 与代理 (Proxy)：虽然后端装了 cors，但在开发环境我用了 Vite 的 server.proxy。
- 前端请求 /api/songs -> Vite 转发 -> localhost:3000/api/songs。
- 这样既解决了跨域，又让前端代码看起来像是在请求同源接口。
数据消费 (Pinia)：
- 在 Store 里写 fetchSongList，拿到数据存进 state。
- 配合 pinia-plugin-persistedstate，刷新页面数据还在，体验极佳。

可视化大屏部署踩坑实录

Sun, 07 Dec 2025 00:00:00 GMT

前言

近期承接了一个可视化大屏的业务，并借助 AI 和文档支持，先后实践了命令行和可视化面板这两种前端项目部署方式。在此复盘部署过程中踩过的坑，以及不同路线的选型取舍，为纯静态站点的部署积累实践经验。

第一步：服务器选购配置建议

由于前期采用按需配置思路不够明确，入手了一台 4核 4G 的服务器。但对于纯静态网站（Static Site）的部署而言，这个配置存在性能冗余。如果只是部署前端静态页面，未引入服务端渲染（SSR）或数据库服务，入门级的 1核 2G 甚至更低配置完全够用。

第二步：命令行部署方式 (Bash / PowerShell + serve)

为了弄懂原理，我先尝试了最原始的命令行方式。虽然过程坎坷，但学到了很多底层逻辑。

流程复盘

环境准备：登录服务器，安装 Node.js 和 npm。
文件上传：使用 scp -r 指令直接从本地把 dist 文件夹传到服务器。
启动服务：安装 serve (npm install -g serve)，然后监听端口启动。
防火墙设置：这是最容易忘的一步！必须去腾讯云控制台的防火墙里放行对应端口。

💡 踩坑与经验

AI 虽好，尽信书不如无书：腾讯云自带的 AI 助手在服务器相关问题很聪明，但是比较难进行提示词工程，外部的ai比较容易自定义，我用起来比较顺手，但是给出的指令有时候是通用的（比如其他地方默认用户名是 root），而腾讯云 Ubuntu 实例的默认用户名其实是 ubuntu，因为这个问题也害我多做不少无用功。
执行指令前要“二审”：AI 给出的指令，最好先问问另一个 AI “这条指令是干嘛的”，确认无误再执行，防止误操作。
排错优先级：官方文档/说明书 > 独立思考 > 问 AI。不要一上来就问 AI，很容易被带偏。

第三步：可视化管理面板部署 (1Panel)

在折腾完命令行后，尝试了现代化的服务器图形化管理工具 1Panel（类似宝塔等服务管理面板）。

体验与优势

界面化运维：将常规文件上传、解压、移动等指令映射为可视化操作，降低失误率。
便捷的拖拽上传：越过基础 scp 或者 sftp 命令的路径配置痛点。
傻瓜式配置：
- 安装 OpenResty / Nginx 容器环境。
- 一键配置反向代理、静态根目录和端口监听。

结果评估

依托可视化面板操作，能够快速构建出可复用的部署路径，将部署交付时间压缩至更低的维度。

总结

两种部署方式的对比总结：

若以夯实 Linux 基础为目标，推荐使用 命令行部署。能从中建立起包括文件权限、端口监听以及云端防火墙配置等一系列底层运维认知。
若以业务系统快速上线为目标，推荐使用 1Panel 等容器化或可视化运维工具。其可显著减少不必要的开发配置时间。

开源破冰：首个高星项目 PR

Sat, 29 Nov 2025 00:00:00 GMT

核心思考

今天最大的感触是：开源贡献的门槛，其实都在“代码之外”。 给大型项目（如 Dify、Ant Design）修 bug 未必需要极高的技术储备，有时只是给 CSS 加个 z-index。 难的不是写那一行代码，而是敢去领 Issue，耐心配置环境（熟练使用 Docker 是关键），以及严格遵循开源社区的 PR 流程。 只要迈出第一步，大型开源项目也是相对容易参与的。

知识内化与经验总结

关于 good first issue（新手村任务）：以前不知道从哪下手，今天才发现这个标签就是给新手的“入场券”。它不需要你懂整个项目的架构，可能只是修个文档、改个样式。 我的理解： 不要看不起小修小补，这是熟悉开源流程的最佳练兵场。先混个脸熟，再图谋大事。
关于“环境配置”是最大的拦路虎：改代码 5 分钟，配环境 2 小时。为了跑起 Dify，我第一次被迫学会了用 Docker。 我的理解： 以前觉得 Docker 麻烦，现在才懂它是开源协作的神器。如果没有它，光是统一几百个开发者的本地环境就能把维护者累死。
关于 AI 结对编程：从“怎么领 Issue”到“怎么规范提交 Commit”，全靠 AI 手把手教。 我的理解： AI 就像一个经验丰富的开源老兵，它填补了我对“潜规则”和“流程”的认知空白，让我能专注于解决问题本身。

从类型契约到云端直传

Thu, 27 Nov 2025 00:00:00 GMT

核心架构思考

数据的单一来源 与 规避代码坏味道 构成了前后端规约及业务联调过程中的准则。如果在前端组件中随处将 CDN 协议及域名写死（例如 http://cdn.xxx.cn/...）进行访问和展示的话，将会极大地增加工程长期维护的包袱。

核心准则：数据库存“相对路径”获取物理灵活性，前端在运行时拼接“绝对路径”满足渲染需求。 这种架构隔离方式，使得资源域名发生变化时，只需在基础配置常量处修改一层即可，业务层的多处调用完全解耦。

知识内化与经验总结

接口契约（api.d.ts）的边界与作用：契约文件不仅仅是后端服务提供的“调用说明书”，更是自动化的“前置保镖”。配合 TypeScript 体系，可以在开发或编译时便能规避不规范或者突变的入参类型，提前防御潜在的调用灾难。自动生成的请求类型层更是能避免双端沟通的滞后问题。
前端云存储直传流程解析：相比由后端接收资源流再传输至 OSS/COS 节点的方式，前端直传规避了由于后端宽带和业务阻塞导致的上传瓶颈。具体的流转时序如下：
- 请求凭证（后端）：生成包含上传有效期的 STS“通行证”（临时密钥），不承担文件实体流转（节省带宽成本）。
- 发起上传（前端）：附带 STS 凭证，依照特定签名将表单格式的二进制文件推至腾讯云（COS 等）。
- 返回元数据（云存储）：下发成功回执，返回文件上传最终落地的路径和名称。
- 信息闭环：前端将纯相对路径推给业务后端落库。
CDN 存储最佳实践： “相对路径”是核心特征，“绝对路径”是端态映射。 在数据库底层维护如 cat/avatar/xx.jpg 的纯相对路径；在前端渲染或网络请求层，基于全局通用函数诸如 getCDNUrl(path) 做协议或域名的动态组装。这种范式让基础设施或者提供商在未来具备无痛切流和迁移的能力。

总结

不管是“云开发机制”还是“CDN全链路”，其底层拆解后依然是受限于计算机网络通信与架构设计的字符串流转。通过剔除工程当中的“代码坏味道”，技术解构所带来的架构清爽度才是前端工程化的魅力所在。

地图选点与瀑布流实践

Thu, 27 Nov 2025 00:00:00 GMT

核心交互顿悟

交互模型：地图选点的逆向思维：通常可能会将选点视为“点击地图目标坐标以转移图钉”。实际上，目前最主流且流畅的体验是**“固定中心图钉，移动地图底图”**。即屏幕中心的交互反馈点始终如一，用户移动的是底层的数据映射图层。
布局模型：瀑布流的本质渲染调度：相较于依托复杂的 CSS 栅格，利用 JS 维护并行数组列去分配图片资源更加具备生产力与适应性。结合 widthFix 或者宽带限制进行高度自适应延展，即可在移动端上建立流畅的渲染模型。

技术内化复现解析

🗺️ 技能一：拖动地图选址（Map Dragging）

这是一个“配置+布局+逻辑”的组合拳。

1. 权限配置（门票） 在 app.json 中必须声明，否则 wx.getLocation 直接报错。

"permission": { "scope.userLocation": { "desc": "用于定位" } },
"requiredPrivateInfos": ["getLocation"]

2. 布局技巧（定海神针） 核心是层叠布局。

容器：position: relative。
地图：铺满容器。
图钉：position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%);。
动画：监听拖动状态，拖动时 translate Y 向上位移更多（抬起），停止时复位（扎下）。

3. 核心逻辑（取值） 不要在拖动过程中疯狂更新，只在停下那一刻取值。

监听：bindregionchange 事件。
判断：e.type === 'end' 且 e.causedBy === 'drag'。
获取：调用 mapCtx.getCenterLocation() 拿到当前地图中心的经纬度。

🌊 技能二：相册瀑布流（Waterfall Layout）

我们采用了JS分列 + Flex布局的方案，比纯 CSS 更可控。

1. 核心原理（发牌算法） 准备 3 个数组（左、中、右），遍历图片列表，按顺序轮询分配。

// 伪代码：Round-Robin 分配
images.forEach((img, index) => {
  if (index % 3 === 0) leftList.push(img);
  else if (index % 3 === 1) centerList.push(img);
  else rightList.push(img);
});

2. 关键属性（自适应高度） 在 WXML 中，图片组件必须设置 mode="widthFix"。这样我们只需要用 CSS 固定每列的宽度（例如 32%），图片高度就会根据原图比例自动撑开，形成错落有致的效果。

总结

看似复杂的端上交互模式脱离表现层后，实际上依然是朴素的结构化算法支撑：地图拖曳是相对平移下的监听映射，瀑布流是列阵集合的任务调度分发。从工程角度建立模型从而实现降维解法，是前端走向进阶所需要掌握的重要能力。

从手抄代码到初涉工程化

Wed, 26 Nov 2025 00:00:00 GMT

核心复盘与顿悟

写代码最难的不是语法，而是“定义需求”：以前遇到“继续游戏”这种功能，经常陷入上来就写 router.push 的局限。事实上必须先反问“什么是继续游戏”、“中断点存在哪”等边界条件，在实现复杂需求前把业务状态流转梳理清晰，后续代码落地才能顺水推舟。
工程化开发不是堆砌功能，而是“制定规则”： “继续游戏”看似简单，实质是对游戏状态机甚至持久化体系的完整建模。路由守卫不再是单纯的拦截器，而是维护整个系统一致性的规则关卡。

知识内化与经验沉淀

🛠️ 工程化思维

拒绝重复造轮子：以前开新项目靠复制粘贴，今天把模板传到 GitHub，配合 new-ccb 脚本，一行命令拉取环境。GitHub 是仓库，脚本是物流车，自动化才是程序员该干的事。

🏗️ 架构与逻辑设计

显式优于隐式（以 Continue 功能为例）：纠结过用路由守卫自动记录路径，但最终选择在关键页面手动更新 continuePath。虽然多写一行代码，但逻辑绝对可控，避免了误触等垃圾信息。
Pinia 的角色划分与持久化：
- 持久化：不用自己操心 localStorage，Pinia 配合插件既有响应式又能自动存本地。
- 边界清晰：队伍、关卡、游戏全局状态拆分成不同的 Store，各司其职，避免大杂烩。
Router 即流程：未选角不能进地图、未通关不能进下一关。这些规则写在守卫里，Router 就成了维护游戏流程完整性的核心骨架。

总结

将需求前置，通过清晰的状态管理和确定的规则执行，能够最大程度提升代码的可控性。从“手工作坊”般复制粘贴代码，切入到具备可组装、自动化流程的工程思维，这正是长期系统建设中的重要基石。

莫莫的博客

Vue 3 响应式原理

一句话摘要

目录

核心数据结构

核心函数

1. effect：副作用函数

2. track：依赖收集

3. trigger：派发更新

响应式更新流程

如何拦截 set 和 get

反射和代理

加入 track 和 trigger

详细运行过程

1. 建立响应式对象

2. 初次执行 effect 并收集依赖（track）

3. 修改数据并自动派发更新（trigger）

本章小结

第三步的延伸：如果在外部再加入一个独立的 get 操作，会有什么问题吗？

本章小结

ref 的实现

computed 的实现

本章小结

总结

RAG 知识库搭建经验总结

一句话摘要

目录

背景与问题

本章小结

关键思路

为什么需要 Vercel AI SDK

本章小结

实践过程

步骤1：业务链路与数据融合

步骤2：数据加载与切块（Loaders & Splitters）

步骤3：向量化与入库（Embeddings & Vector Stores）

步骤4：检索召回流（Retriever Pipeline）

本章小结

结果与复盘

PDF 解析问题

批量导入过大

结构化输出

TDD

从手动上传到自动发布：我给项目接入 CI/CD 的完整复盘

一句话摘要

目录

背景与问题

本章小结

最终方案

本章小结

实践过程

步骤 1：调整服务器目录结构

步骤 2：让 OpenResty 读取 current

步骤 3：编写服务器发布脚本

步骤 4：生成 GitHub 用的 SSH 密钥

步骤 5：配置 GitHub Secrets

步骤 6：添加 GitHub Actions 工作流

本章小结

踩坑复盘

坑 1：pnpm/action-setup 版本冲突

坑 2：Lighthouse 上没有 nginx 命令

坑 3：宿主机路径和 OpenResty 容器路径不是一回事

坑 4：current 软链接用了绝对路径，导致 500

坑 5：浏览器显示旧页面，不代表服务器正常

本章小结

增量部署的实现

为什么不是继续用压缩包

rsync --link-dest 怎么做到增量

为什么还要保留 current

和压缩包部署相比，它解决了什么

本章小结

跑通后的完整链路

本章小结

后续优化

1. 限制发布权限

2. 不再直接用 root 做部署

3. 进一步处理 PWA 缓存更新体验

本章小结

总结

深入理解浏览器的事件循环与异步机制

步骤 2：让 OpenResty 读取 `current`

坑 1：`pnpm/action-setup` 版本冲突

坑 2：Lighthouse 上没有 `nginx` 命令

坑 4：`current` 软链接用了绝对路径，导致 500

`rsync --link-dest` 怎么做到增量

为什么还要保留 `current`

2. 不再直接用 `root` 做部署