SunZhongyi's Blog

React组件生命周期

SunZhongyi — Fri, 02 Jun 2023 00:00:00 GMT

谈论 React 的生命周期通常是基于类组件的，在 React 中引入函数组件后，类组件的生命周期方法并不适用于函数组件。函数组件依赖于 React Hooks 来管理状态和副作用。

类组件生命周期

React 类组件中，React 的生命周期可以分为三个主要阶段：

挂载阶段 Mounting
- constructor(props): 在组件挂载之前调用。通常用于初始化状态和绑定事件处理程序
- static getDerivedStateFromProps(props, state): 从 Props 派生状态，该钩子基本不会使用。
- render()：必须实现的方法，返回 React 元素(jsx 描述)
- componentDidMount()：在组件挂载后立即调用。通常用于进行网络请求或订阅
更新阶段 Updating
- static getDerivedStateFromProps(props, state)：同上
- shouldComponentUpdate()：返回一个布尔值，决定组件是否应更新。用于优化性能
- render()：同上
- getSnapshotBeforeUpdate(prevProps, prevState)：在 DOM 更新前调用，常用于捕获一些 DOM 更新之前的一些状态(例如滚动位置)，该函数可以返回任意值，返回的值将作为 componentDidUpdate 的第三个参数
- componentDidUpdate(prevProps, prevState, snapshot)：在组件更新后立即调用。用于处理 DOM 操作或网络请求。
卸载阶段 Unmounting
- componentWillUnmount()：当组件从 DOM 中移除时调用

详细的可以参考这里： link.

函数式组件中的生命周期

类组件每个阶段都有不同的生命周期钩子函数，一共有很多钩子，这里不详细展开研究。且着重使用的就三个，分别是 componentDidMount、componentDidUpdate、componentWillUnmount 。函数组件依赖于 React Hooks 来管理状态和副作用，下面列出了关键 Hook —— useEffect() 和这三个钩子的映射关系。

具体生命周期方法在类组件和函数组件中的对应关系如下：

componentDidMount(无参数): 在组件挂载后执行。

对应的 Hook: useEffect(() => { /_ 逻辑 _/ }, []);

componentDidUpdate(prevProps, prevState): 在组件更新后执行。

对应的 Hook: useEffect(() => { /_ 逻辑 _/ });

componentWillUnmount(无参数): 在组件卸载前执行。

对应的 Hook: useEffect(() => { return () => { /_ 清理逻辑 _/ }; }, []);

通过使用 Hooks，函数组件能够实现类组件生命周期方法中的大部分功能，同时代码更加简洁和易于理解。

类组件中通常在 componentDidMount 钩子中去发送请求，在函数式组件中式在 useEffect 中去发送请求，useEffect 模拟了 componentDidmMount 这个钩子。

React组件通信

SunZhongyi — Mon, 05 Jun 2023 00:00:00 GMT

子 -> 父

也是通过 props，只不过是父组件传递函数到子组件，子组件调用这个函数，并传入参数。
父组件在这个函数被调用的时候，通过接收参数实现。

兄弟组件通信

兄弟组件通信是通过最近的公共父组件作为桥梁实现的。
也就是在公共组件父组件中

传递给 A 组件一个函数，
传递给 B 组件一个 state.

然后从 A 组件传递数据到 B 组件。
步骤就是先子(A)传父(公共组件), 然后(公共组件)父传子(B)

跨层级通信

React.createContext

使用 React.createContext() 创建上下文对象
并在组件中使用 Provider 提供数据，
子组件通过 Consumer 或 useContext 获取数据。

发布订阅模式

使用 mitt.js 发布订阅库示例：

有以下文件目录：

.
├── App.jsx
├── Mitt.js
└── components
    ├── A.jsx
    └── B.jsxcopy success

文件内容如下：

// App.jsx
import A from "./components/A";
import B from "./components/B";
export default function App() {
    return (
        <div className="comps">
            <A />
            <B />
        </div>
    );
}

// A.jsx
import Mitt from "../Mitt";
import { useState } from "react";

export default function A() {
    const [input, setInput] = useState();
    const handleInputChange = (e) => {
        setInput(e.target.value);
        Mitt.emit("hello", e.target.value);
    };
    return (
        <div className="comp-a">
            <input type="text" value={input} onChange={handleInputChange} />
        </div>
    );
}
// B.jsx
import { useState } from "react";
import Mitt from "../Mitt";
export default function B() {
    const [state, setState] = useState("-");
    Mitt.on("hello", (val) => {
        setState(val);
    });
    return (
        <div className="comp-b">
            <p>component b: {state}</p>
        </div>
    );
}
copy success

全局通信

和 Vue 一样，也是通过全局状态管理库来实现的。
比较流行使用的有Redux, Mbox, Zustand

递增（增量）轮询

SunZhongyi — Tue, 27 Jun 2023 00:00:00 GMT

我们平常开发中，经常用到，轮询。但是有些场景下，对某些轮询有一些额外的要求。例如我现在公司在做的项目中，后台有队列任务，如果队列任务少，或者空闲的话，那么这个任务很快就能够完成，否则，就需要排队。

那么一开始，前台发送了一个任务执行请求的时候，接着前台这边会开始轮询这个任务的执行状态，完成了没有。设定的轮询时间是5秒。

但是前台的反馈就会有一个问题，哪怕这个任务在1秒钟就完成了。前台也不会变更状态，只有等5秒后的下一次请求，然后再变更页面状态。

我们这个业务暂时没有用到 socket，所以实时性没有那么高。

那有没有别的思路呢？

如果我直接将间隔时间调整为很短，这样页面确实可以较快响应任务的状态变更。但是如果任务很多的时候，后台压力会很大。

是否可以假设，前台每次请求执行一个任务后，我先是间隔很短的去轮询，如果后台队列比较空闲，那么很快就能更新状态了，然后我慢慢的递增间隔的轮询时间，直到一个设定的最大值。

假设，我起始最少间隔是200毫秒，然后递增步长是100毫秒，最大间隔是1500毫秒。

现在如果有一个任务请求执行需要1秒，那么我会分别以以下间隔发送请求：

200ms,200ms+100ms,200ms+100ms+100ms,200ms+100ms+100ms+100mscopy success

四次请求的总时长为 1400ms, 所以我在第四次请求就能够更新页面状态了，

而如果某个任务请求执行需要10分钟，那么前台会一次累加请求的间隔时间，200ms,300ms,400ms,500ms,.....直到1500ms, 此时如果状态还没有完成，那么后面就每隔1500ms去查询一次。

实现

根据以上思路，我们有如下实现：

/**
 *
 * @param min 起始间隔
 * @param max 最大延迟
 * @param step 步进延迟
 * @param cb 回调函数(执行函数)
 * @param immediate 是否立即执行
 * @param _count (私有属性，也可以传递，传递后首次延迟将会是 min + step * _count)
 */
const incrementWalk = function (min: number, max: number, step: number, cb: () => void, immediate = false, _count = 0) {
    immediate && cb();
    // console.time()
    const nextDelay = min + step * _count
    setTimeout(() => {
        // console.timeEnd()
        incrementWalk(min, max, step, cb, immediate, _count + 1)
    }, nextDelay > max ? max : nextDelay)
}

const callback = () => {
    console.log("trigger")
}

incrementWalk(100, 5000, 300, callback, true)copy success

递增（增量）轮询，解决了什么问题？

解决了在某个任务耗时不确定，又希望尽快刷新页面状态，同时又要兼顾服务器压力问题。

递增（增量）轮询

SunZhongyi — Tue, 27 Jun 2023 00:00:00 GMT

那么一开始，前台发送了一个任务执行请求的时候，接着前台这边会开始轮询这个任务的执行状态，完成了没有。设定的轮询时间是5秒。

但是前台的反馈就会有一个问题，哪怕这个任务在1秒钟就完成了。前台也不会变更状态，只有等5秒后的下一次请求，然后再变更页面状态。

我们这个业务暂时没有用到 socket，所以实时性没有那么高。

那有没有别的思路呢？

如果我直接将间隔时间调整为很短，这样页面确实可以较快响应任务的状态变更。但是如果任务很多的时候，后台压力会很大。

假设，我起始最少间隔是200毫秒，然后递增步长是100毫秒，最大间隔是1500毫秒。

现在如果有一个任务请求执行需要1秒，那么我会分别以以下间隔发送请求：

200ms,200ms+100ms,200ms+100ms+100ms,200ms+100ms+100ms+100mscopy success

四次请求的总时长为 1400ms, 所以我在第四次请求就能够更新页面状态了，

实现

根据以上思路，我们有如下实现：

/**
 *
 * @param min 起始间隔
 * @param max 最大延迟
 * @param step 步进延迟
 * @param cb 回调函数(执行函数)
 * @param immediate 是否立即执行
 * @param _count (私有属性，也可以传递，传递后首次延迟将会是 min + step * _count)
 */
const incrementWalk = function (min: number, max: number, step: number, cb: () => void, immediate = false, _count = 0) {
    immediate && cb();
    // console.time()
    const nextDelay = min + step * _count
    setTimeout(() => {
        // console.timeEnd()
        incrementWalk(min, max, step, cb, immediate, _count + 1)
    }, nextDelay > max ? max : nextDelay)
}

const callback = () => {
    console.log("trigger")
}

incrementWalk(100, 5000, 300, callback, true)copy success

递增（增量）轮询，解决了什么问题？

解决了在某个任务耗时不确定，又希望尽快刷新页面状态，同时又要兼顾服务器压力问题。

箭头函数中的this指向

SunZhongyi — Sat, 08 Jul 2023 00:00:00 GMT

[toc]

一、函数中的`this` 指向

1.1 示例1:

const name = 'window';
(function () {
  console.log(this.name)// window
})()copy success

等同于：

const name = 'window'
function func() {
  console.log(this.name)// window
}

window.func() // 可简写为 func();copy success

示例2:

const obj = {
  name: 'obj',
  func() {
    console.log(this.name)// obj
  },
}
obj.func()copy success

从上面两个示例中可以得出，似乎，函数体中this 好像指向函数定义所在作用域对象中。在这里，便是window 对象。这是初步可以得出的结论。

为了进一步验证，我们使用call来改变函数的调用对象试试：

const obj = {
  name: 'obj',
}

const name = 'window'
function func() {
  console.log(this.name)
}
window.func.call(obj)// objcopy success

可见, 确实, 普通函数体中的this 指向调用该函数的对象, 即"调用者对象".

2. 箭头函数中的`this` 指向

示例1:

const name = 'window'

const obj = {
  name: 'obj',
  func: () => {
    console.log(this.name)
  },
}
obj.func()// windowcopy success

可见, 即便func()函数的调用对象是obj,但是输出结果却是window

React应用的创建

SunZhongyi — Tue, 11 Jul 2023 00:00:00 GMT

一、CDN Demo 引用

以下是一个在 cdn 中初试 react 的 demo:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <!-- core react library -->
    <script src="https://unpkg.com/react@18.3.1/umd/react.development.js"></script>
    <!-- react-dom 用于浏览器渲染，react 还可以开发原生应用这时候就依赖react-native -->
    <script src="https://unpkg.com/react-dom@18.3.1/umd/react-dom.development.js"></script>
    <title>Hello React!</title>
  </head>

  <body>
    <div id="root"></div>
    <script>
      function App() {
        const [time, setTime] = React.useState(new Date().toLocaleTimeString())
        React.useEffect(function () {
          setInterval(function () {
            setTime(new Date().toLocaleTimeString())
          }, 1000)
        }, [])
        return React.createElement('header', null, `Hello React! ${time}`)
      }
      const root = ReactDOM.createRoot(document.getElementById('root'))
      root.render(React.createElement(App))
    </script>
  </body>
</html>copy success

React 是一个 JS 库， React 的官方说它严格意义上并不是一个框架，它只注重 UI 层面。

React 的执行，依赖两个核心：

react : React 的核心逻辑库
react-dom: React 的渲染逻辑库，它负责将内容渲染到网页中。

React 还可以用于写原生应用，这时候，React 的核心逻辑是一样的，不过渲染库就不再是 react-dom 了。而是 react-native

二、脚手架

目前 React 的主流创建方式有两种选择：

Create-react-app
create-react-app 是一个官方的用于创建基于 React 的 SPA 应用的 CLI 工具
Vite

利用 Create-react-app 创建 React 应用

利用 create-react-app 最简单地创建一个 react 应用：

npx create-react-app my-app
copy success

--template 参数

--template 参数用于指定模板, 其用法如下：

npx create-react-app my-app --template [template-name]copy success

# 创建 ts 项目
npx create-react-app my-app --template typescriptcopy success

更多的 template，可以在 npm 上搜索 "cra-template-*" 以查看更多

使用不同的包管理工具

要使用不用的包管理工具，只需要在执行 create-react-app 的使用，用不同的包管理工具即可，例如：

# 默认使用npm
npx create-react-app my-app
#使用 yarn
yarn create react-app my-appcopy success

利用 Vite 创建 React 应用

使用 vite 创建 react 应用很简单，只需要：

# 使用pnpm 创建
pnpm create vite
# 然后按需选择工具就可以了copy success

React是怎么运行的

SunZhongyi — Thu, 13 Jul 2023 00:00:00 GMT

一、Component、Instance、和 Element、DOM Elements 四者的关系

组件 Component

组件是 UI 的 描述 Description
一个组件就是一个返回 React Elements(element tree) 的函数，通常使用 JSX 编写
可以将 Component 理解为一个蓝图或者模板 (Blueprint/Template)

function Card() {
  return (
    <div className="card">
      <p>Hello</p>
      <p>React!</p>
    </div>
  )
}copy success

Instance

当一个组件 Component 被使用的时候，实例就会被创建
React 内部实际上会去调用组件函数
每个组件实例拥有自己独立的 state 和 props
每个组件实例有自己的生命周期，包括诞生，生存，消亡(be born/lilve/die), 也叫：挂载（mounting）、更新（updating）、卸载（unmounting）。

export default function App() {
  return (
    <>
      <header>This is header</header>
      <Card />
      {/* 这里使用Card就会创建 Card 这个组件的实例 */}
      <Card />
      <Card />
      <footer>This is footer</footer>
    </>
  )
}copy success

React Element

JSX 将会被转换为 React.createElement() 方法
React.createElement() 方法执行后返回的结果就是 React Element
React Element 中会含有一些必要的信息用于创建真实的 DOM Elements

React 通过 Babel 来转换 JSX 语法，我们可以通过以下示例体验具体的转换结果。
可以直接在 babel 的官网 playground 查看，可以通过下面的步骤手动尝试。

以下是官网的转换截图：

# 项目初始化
mkdir babel-jsx; cd babel-jsx
npm init -y
# 安装 @babel/cli @babel/core 和 @babel/preset-react
pnpm add --save-dev @babel/core @babel/cli @babel/preset-react
# 创建babel 配置文件 babel.config.json
# 内容如下：
{
    "presets": [
        "@babel/preset-react"
    ]
}
# 创建待转换文件
mkdir src; touch src/main.jsx # 在main.jsx 中写入需转换的 jsx 代码

# 执行转换指令
./node_modules/.bin/babel src --out-dir lib

# 转换结果输出为 lib/main.jscopy success

DOM Elements

DOM Elements 就是浏览器上真实的 DOM， React 通过 React Element 中的必要信息创建这些真实的 Dom 元素。

这四者的大致过程如下图所示：

具体的组件是如何被展示到屏幕上的，还需要更进一步分析：

p121

二、组件被展示到屏幕上分为四个步骤，分别是：

触发组件 render

大多时候，组件的渲染，通过某些地方的 state 更新而触发。注意，在 React 中，如果父组件的 state 更新，那么所有子组件都将触发更新。
render 阶段

在这个阶段， React 通过调用组件函数并分析将如何更新 DOM，但是在这个阶段，页面还不会重新渲染。Rendering 发生在 React 内部，并不会产出任何视觉上的变化。
commit 阶段

在这个阶段， React 将会着实的修改 DOM，包括插入/更新/删除元素。
浏览器绘制

这个阶段就和 React 本身没有关系了。

值得注意的是，

通常，人们 语义上 提及 Rendering 的时候，实际上可能指的是 Render 阶段 + Commit 阶段

有两种场景会触发 Render:

应用初始化

State 更新

Render 并不是立即触发，而是异步的，同时会合并同步的 setState 行为

Render 阶段

在深入接下来的内容之前，有两个误区需要先指明：

Rendring 就是更新屏幕或者 DOM ❌

刚才已经说过了， Rendring 实际上不不包含视图或者 DOM 的修改的, 视图/DOM 的修改发生在 Commit 阶段。后文会详细说明。
在 Re-render 的时候 React 完全丢弃旧的 DOM ❌

并不会完全丢弃旧的 DOM, 下文会详细说明。

虚拟 DOM（React Element Tree）

React 中，一个 React 应用，都是由组件嵌套而成，最终形成一个大的组件树。组件树只是一个高层的抽象。React 底层会将这个组件树转换为一个 React Element 树。这个树 也被称为虚拟 DOM (官方不再这么称呼)。它实际上就是一个树形的 JS 对象。

当某个组件的 State 发生更新时，将会触发 Re-render 流程。组件树就会形成一个新的虚拟 DOM。 再次强调，这个过程（render/re-render），只是更新虚拟 DOM，并不会直接修改真实 DOM.

❓ 为什么不重用虚拟 DOM ,而是直接重新构建新的虚拟 DOM 呢？

简化逻辑：重用相对直接构建更复杂，存在潜在风险
稳定性和一致性：避免因为重用旧的虚拟 DOM 从而引起潜在状态不一致或者错误
Fiber 架构优化：Fiber 架构支持增量渲染和优先级调度，使得虚拟 DOM 的重建过程和比较过程性能良好

注意： 父组件一旦触发更新，子组件也会触发更新，不管其 Props/State 有没有发生改变。

上图中，如果 A 根组件触发了更新，那么整个组件树都将触发更新，因为 React 无法知道子组件是否会被影响。

❓ 为什么底层会维护一套虚拟 DOM 呢？原因在于相比于直接操作 DOM 元素，虚拟 DOM 的操作开销要小的多。

Reconciliation(调和/协调)

我们需要带着两个核心问题去深入：

是什么？
为什么需要它？

为什么不在有 state 变动的时候直接更新整个 DOM 呢？这是因为直接更新整个 DOM 这个操作低效且浪费资源。因为首先相对于 JS 内存数据操作来说，DOM 操作缓慢的；此外，大多数时候，页面上只有一小部分区域内容需要被更新。

所以， React 会尽可能的重用即存的 DOM。那么 React 怎么实现最大重用的呢？就是通过 调和机制。

Reconciliation 调和过程就是分析 Re-render 的时候，到底哪些 DOM 元素需要被插入/删除/更新

Fiber 的概念

Fiber 是 React 内部使用的一种数据结构

Fiber 树是由 Fiber 节点链接而成的数据结构。是一种链表结构。具体的结构描述为，每个父元素和其第一个子元素建立一个链接，其他子元素和兄弟元素之间建立链接。

Fiber 架构

Fiber 架构即基于 Fiber 的架构设计。它出现的目的为了提高调和过程的性能和效率。 Fiber 的引入使得 React 能够更加灵活高效地处理 UI 更新。

Fiber 架构有这样几个优点：

增量渲染： Fiber 将调和过程分解为多个小任务，可以在浏览器的帧之间进行分段执行，避免传统调和过程的递归机制导致的长时间阻塞。
优先级调度：Fiber 架构允许 React 根据不同的任务重要性分配优先级，高优先级任务可以打断低优先级任务，从而提高应用的响应性。
细粒度更新：每个 Fiber 节点表示一个虚拟 DOM 节点或者组件示例，包含其状态，属性和相关信息，便于精确管理和更新。

Reconciler 调和器的概念以及和 Fiber 的关系

Reconciler 是 React 中的调和器。它用于

确定 UI 的哪些部分需要更新
生成更新操作。

Fiber 是 Reconciler 的基础结构
1. Fiber 架构是 Reconciler 的基础， Reconciler 依赖 Fiber 节点来表示和管理虚拟 DOM 树。
2. 每个 Fiber 节点包含了虚拟 DOM 节点的类型、属性、状态等信息，并通过链表结构连接起来，形成 Fiber 树
调和过程中的协同工作：
1. 在调和过程中， Reconciler 会通过 Fiber 树对比新的虚拟 DOM 和当前的 Fiber 树。
2. Reconciler 根据新的虚拟 DOM 生成或者更新 Fiber 节点，形成新的 Fiber 树。

调和过程的具体步骤

首次渲染
首次渲染的时候， React 从根组件开始构建一颗 React Element 树，也叫虚拟 DOM。并基于该虚拟 DOM ，构建一棵 Fiber 树。

Fiber 树有几个重要特征：

Fiber 树的每个节点称为 Fiber, 每个 Fiber 都对应了某个组件实例和 DOM 元素，可以理解为一种映射关系，Fiber 会持有映射组件的当前状态，Props,副作用等信息
区别于虚拟 DOM 中的 React 元素，每次更新都会导致完全构建新的虚拟 DOM。 Fiber 树一旦创建，后续的每次渲染，该 Fiber 树并不会完全重新创建，只会局部的变更。
Render 阶段中，得益于 Fiber 架构，Rendering 处理可以被切分为多个 chunks，任务执行可以被优先级调度，整个过程可以被暂停，重用，或者移除。这样一来就不会阻塞浏览器的渲染线程。
初始渲染
1. React 创建初始的虚拟 DOM 树和对应的 Fiber 树。
2. Fiber 树用于管理虚拟 DOM 节点和组件实例。
状态或者属性更新
1. 当组件的状态或者属性发生变化时，生成新的虚拟 DOM 树。
2. Reconciler 对比新的虚拟 DOM 树和旧的 Fiber 树，找出差异。
更新 Fiber 树：
1. Reconciler 根据新的虚拟 DOM 生成新的 Fiber 节点，并更新 Fiber 树。
2. 标记需要更新的节点，并记录需要进行的 DOM 操作
提交阶段：
1. Reconciler 将生成的更新操作应用到实际 DOM 中，更新 UI.

showModal 只 App 组件中的 state，当该 state 发生更新，将会触发 Re-render。
父组件更新，所有子组件也会更新。
React 会构建一棵新的虚拟 DOM 树，

应用第一次创建的时候，会通过虚拟 DOM 构建一棵 Fiber 树，Fiber 树是一个链表结构，每个元素节点都会链接子节点和兄弟节点。
紧接着， React 进入调和+Diff 过程，该过程以旧的 Fiber 树和新的虚拟 DOM 为输入，将新的虚拟 DOM 和当前的 Fiber 树进行调和。

React 将基于新的虚拟 DOM 对该 Fiber 树进行遍历，对这个 Fiber 树一个节点一个节点的分析需要更改的内容，这个过程称之为 Diffing, 变更后的这棵 Fiber 树在内部被称为 workInProgress 树。在这棵树中，图中示例， Btn 按钮文字部分被标记为更新，而由于 Modal 及其子元素不存在于新的虚拟 DOM，因此这些节点在 Fiber 树种被标记为删除。而 App 以及 Video 元素虽然也参与到了 Re-render 流程，但是由于新的虚拟 DOM 中，这些节点没有变更，因此 Fiber 将不会被做任何标记处理，从而达到了重用的目的。

这些变更将会被收集到一个称之为副作用列表的数据对象中，用于供给下一个阶段——Commit 阶段，去实际的修改 DOM。

Render 阶段图示总结

下面对 Render 阶段（Re-render）进行总结。

当组件实例触发了 re-render, 产生新的虚拟 DOM，然后 React 将进入调和流程，将基于新的虚拟 DOM, 对当前的 Fiber 树进行遍历，标记所有需要更新的 Fiber 节点信息。调和过程的结果就是产生更新后的 Fiber 树。然后 React 将所有需要更新操作收集起来 (list of effects) 交给下一个 Commit 阶段。

render 函数执行，将会产出 React Elments, React Elment 构建而成的树形 js 数据对象被称之为新的虚拟 DOM

Commit 阶段

在 Commit 阶段，就不再是由 React 完成了，在浏览器中，则是由 React-dom 来接管。

在这个过程中， React-dom 会去进行 DOM 操作，包括插入/删除/更新。
Committing 操作是异步进行的。不可被中断，这样可以避免中断导致的页面部分渲染。导致应用无法正常工作。

在 Commit 阶段完成后， workInProgress fiber 树就成为了当前的 fiber 树。在下一次 render 循环的时候，就会被作为输入处理。

接下来就会交给浏览器去处理绘制。

深入更多

在 Render 阶段， React 只是去找到该怎么 render,并不会触及真实的 DOM 元素。 Commit 阶段才会去执行真正的 DOM 操作。而这个 DOM 操作不仅仅只是浏览器，可以是原生应用。这时候就以来 React Native 或者 Remotion 等其他库。

Diff 具体是怎么执行的？

Diff 有两个重要原则：

两个不同类型的元素，将会产生不同的 Trees
元素的 key 不变，那么将会保持不变

这个操作使得常规 Diff 需要 O(n^3) 的操作复杂度降低为 O(n)。

@refer: https://legacy.reactjs.org/docs/reconciliation.html#motivation

Diff 过程中，只有两种场景需要被讨论：

同位置，不同元素
同位置，相同元素

场景 1. 同位置，不同元素

在第一个示例中，可以看父元素从 <div> 变成了 header
这时候，React 会重建整个元素节点，包括其所有子节点，以及状态。也就是 <div> 和 <Searchbar> 都会从 DOM 中移除。替换为 <header> 和全新的 <SearchBar>。
在第二个示例中， <SearchBar> 元素被替换成了 <ProfileMenu>
有几点可以总结：

当父元素类型变更的时候，React 假定整个子树都失效，重建
旧的组件将会被销毁并从 DOM 中移除，包括其状态也会被重置

场景 1. 同位置，相同元素

在第一个示例中，原生的 <div> 元素没有改变，只是修改了 className, 第二个示例中， <SearchBar> React 元素类型没有改变，只是修改了 props.wait 的值。
这两种情况下，元素都会被保留，包括其状态。
有几点总结如下：

如果同位置的元素类型没有改变，那么元素将会被保留，包括其子树元素。同时会保留其状态
新的 props/atrributes 将会被传入
有的时候，我们不希望这种默认行为，可以通过指定新的 key prop 使得元素强制被更新

下面通过一个 demo 来观察这个过程：

关键代码如下：

export default function App() {
  const [activeTab, setActiveTab] = useState(1)
  return (
    <div className="container">
      <TabList {...{ activeTab, setActiveTab }} />
      <div className="tab-content">
        <Content activeTab={activeTab} />
        <div className="score-footer">
          {activeTab < 4 ? <Score /> : <BlankNotice />}
        </div>
      </div>
    </div>
  )
}copy success

这个组件的基本逻辑是，4 个 tab 显示不同的 content 内容，第四个 tab 种，没有 score 这个打分组件，取而代之的是一个文本提示。此外， Content 组件中维护了一个 state 绑定了 input 元素。

可以看到，当我们先设定了打分，和 input 值。然后在前 3 个 tab 中切换的时候， tab content 的内容改变了，但是 score 的状态还是持有，没有清除。第四个 Tab 中由于替换了 score 元素，切换回去(tab1、tab2、tab3)的时候，score 的状态被重置了。而 input 元素从输入以后，后面的切换始终保持状态。

这些现象正是由于 React 的 Diff 原则所导致的。

当 tab-content 的内容改变，但是元素类型没有变动时。 React 会复用这个元素，并不会销毁。包括其 State, 其内容为动态计算值。
score 组件，由于在前三个 tab 中，同位置的同元素类型没有变更，所以也会被保留复用。包括其状态。但是在第四个 Tab 中，由于元素类型变更，所以 score 元素会被移除替换。下次切换回去的时候，score 元素又被重新创建，因此状态被重置。

那这种场景下，加入我们需要每次 tab 切换 input 和 score 元素都更新怎么办？
只需要通过添加 key 属性，让 React 强制更新即可。

三、React 渲染相关核心概念总结

组件

一个组件相当于一个屏幕上一个 UI 元素的蓝图或者模板。
当我们 “使用” 一个组件的时候， React 将会创建一个 组件实例 (这个过程背后其实就是调用组件函数)，它包含了 Props, State 等等信息。一个组件实例在渲染后将会返回一个 React Element。

Rending 渲染

渲染仅意味着 调用组件函数 和计算哪些 DOM 元素需要被插入，删除，或者更新。但是这个过程实际上并不会做任何的真实 DOM 操作。因此， 每次组件实例被渲染或者重渲染，这个组件函数就会被再次调用。

Each time a component instance is rendered and re-rendered, the function is called again.

触发渲染

只有应用首次渲染和状态更新才会引发一次渲染过程，渲染过程并不是局部发生在某个组件，而是整个应用。

某个组件实例重新渲染的时候，其子组件全部重新渲染

当一个组件实例被触发了重渲染（re-render）的时候，其所有的子树上的子组件都会重新渲染。但是特别注意，这并不意味所有的子组件都会在真实 DOM 上更新。主要是由于 Render 的过程中涉及一个非常重要的流程 —— Reconciliation（调和），在这个过程中， React 会去找到哪些元素确实发生了变更。且会将所有的变更收集起来传递给 Commit 阶段去操作 DOM。

Diff

Diff 是调和 Conciliation 过程中的重要步骤，正式 Diff 使得 React 找到了需要真实被更新的元素。
Diff 的过程简单来说，就是对比新的虚拟 DOM 和当前 Fiber 树，同位置的元素类型是否相同。如果不相同，那么就会销毁旧的元素，更新为新的元素，如果相同，会去检查属性值是否相同，传递新的属性和 Props。

Key 属性

Key 的作用主要有两个，但是归根结底核心就是组件的 Key 发生了更新，那么这个组件一定会被更新。
所以其作用，一方面是提高页面更新的效率，相同 Key 的元素会被保留重用；另一方面，可以利用重设定 Key 来强制更新组件。

这里也能说明，列表渲染的时候，为什么不要使用 index 作为 key，因为 index 不能确保和每个列表元素一一对应，也就做不到重用，提高性能。

永远不要在另一个组件中声明新的组件

永远不要在另一个组件中声明新的组件，因为这么做的话，每次父组件 re-render 的时候，都会重新创建这个嵌套子组件，导致每次父组件状态更新触发 re-render 的时候，子组件都会重置其状态。

错误实践示例：

function ParentComponent() {
  const [parentState, setParentState] = useState(0)

  const ChildComponent = () => {
    const [childState, setChildState] = useState(0)

    return (
      <div>
        <p>
          Child State:
          {childState}
        </p>
        <button onClick={() => setChildState(childState + 1)}>
          Update Child State
        </button>
      </div>
    )
  }

  return (
    <div>
      <p>
        Parent State:
        {parentState}
      </p>
      <button onClick={() => setParentState(parentState + 1)}>
        Update Parent State
      </button>
      <ChildComponent />
    </div>
  )
}copy success

React的批处理更新

SunZhongyi — Fri, 14 Jul 2023 00:00:00 GMT

React 中状态的更新是异步 + 批处理的 Batched

有这样一个示例：

React 在背后将会如何处理同一个上下文中多个 setState 方法？会触发三次 Re-render 吗？ console 打印值将会是什么？是更新后的值吗？

我们知道 React 的更新流程或者说 Re-render 流程， Trigger Render（触发渲染） -> Render Phase（Render 阶段） -> Commit Phase（Commit 阶段）-> 浏览器绘制

❓ 那么示例中的 reset 函数执行会是如下阶段吗？

并不会，React 中， setState 方法是异步执行的，这意味着 setState 方法的执行并不会立即更新组件的状态和重新渲染组件。React 会将多个 setState 状态更新请求放入一个队列中，并在合适的时机进行批量处理。

因此，上面的三次 setState 方法，会被异步的批处理。它们只会触发一次 render + commit 流程。

❓ 那么 console.log(answer) 将会打印更新后的值吗？

并不会，State 在 Render 阶段存储在 Fiber 树中，而在这里，打印的时候， Re-render 流程还没有触发。所以打印将会是旧的值。

我们容易发现一个问题，以上示例是 set 不同的状态，如果有多个更新操作针对同一个 state，最终将会如何影响?

const [count, setCount] = useState(0)
setCount(count + 1)
setCount(count + 1)
console.log(count) // 0
setCount(count + 1)
setCount(count + 1)
console.log(count) // 0
// 页面上的count的引用最终显示1copy success

首先，两次打印，都打印初始值 0，这一点我们在上面已经讨论过，因为 setState 方法是异步执行的。
但是，页面上的值为什么会是 1 呢？

其实，这是因为，像这样调用 setState(count + 1)的时候， count 值始终都是初始值。所以这个过程实际上等同于：

setCount(0 + 1)
setCount(0 + 1)
setCount(0 + 1)
setCount(0 + 1)
// 所以最后结果是1copy success

我们再看一下下面的示例：

setCount(count + 4)
setCount(count + 1)
setCount(count + 2)
setCount(count + 3)copy success

根据上面的分析，我们知道这些操作实际上等同于：

setCount(0 + 4)
setCount(0 + 1)
setCount(0 + 2)
setCount(0 + 3)copy success

每一次执行都会覆盖上一次的结果，因此最后的状态是 3。而由于 React 的更新是批处理的，React 只会触发一次 Render + Commit 流程

❓ 怎么确保每次操作都是基于最新的状态呢？
使用回调函数最为 setState() 方法的参数：

setState((previousState) => {
  return previousState + 1
})copy success

这样每次执行就会基于最新的 State 更新了：

setCount(count => count + 1)
setCount(count => count + 1)
console.log(count) // 0
setCount(count => count + 1)
setCount(count => count + 1)
console.log(count) // 0
// 页面上的count的引用最终显示4copy success

事件处理函数之外的批处理

React18 以上版本，将会批处理除了事件处理函数之外的状态更新，例如计时器 timer,promise, 还有原生点击事件的监听。

示例：

import React, { useState } from 'react'

function BatchingExample() {
  const [count, setCount] = useState(0)

  const handleClick = () => {
    // 在点击事件处理函数中执行多次状态更新
    setCount(prevCount => prevCount + 1)
    setCount(prevCount => prevCount + 2)
    setCount(prevCount => prevCount + 3)
  }

  const handleAsyncOperation = () => {
    // 在异步操作中执行多次状态更新
    Promise.resolve().then(() => {
      setCount(prevCount => prevCount + 1)
      setCount(prevCount => prevCount + 2)
      setCount(prevCount => prevCount + 3)
    })
  }

  const handleTimeout = () => {
    // 在setTimeout中执行多次状态更新
    setTimeout(() => {
      setCount(prevCount => prevCount + 1)
      setCount(prevCount => prevCount + 2)
      setCount(prevCount => prevCount + 3)
    }, 1000)
  }

  return (
    <div>
      <p>
        Count:
        {count}
      </p>
      <button onClick={handleClick}>Update Count (Click)</button>
      <button onClick={handleAsyncOperation}>Update Count (Async)</button>
      <button onClick={handleTimeout}>Update Count (Timeout)</button>
    </div>
  )
}

export default BatchingExamplecopy success

记录useEffect闭包陷阱问题

SunZhongyi — Wed, 02 Aug 2023 00:00:00 GMT

记一次开发问题：

我有一组件A ，如下

// ...... STATE
  const [startTime, setStartTime] = useState(0);// 时间 tag
  const [endTime, setEndTime] = useState(0);
// ...... useEffect
  useEffect(() => {
    const video = videoRef.current;
    if (!video) return;
// ......
    const handleTimeupdate = ()=>{
      console.log('videoRef.current.currentTime',videoRef.current.currentTime, "startTime: ", startTime, "endTime:", endTime)
      if(videoRef.current && videoRef.current.currentTime > endTime){
        // playAtFromRangeStart()
      }
    }
    video.addEventListener("timeupdate", handleTimeupdate)
  }, []);
// ......

// ...... Change state somewhere.
  const handleChange = (/*.....*/,percentage: number) => {
// ......
  const newTime = /* ...... */
    /* ...... */ setStartTime(newTime) : setEndTime(newTime);
// ......
  };copy success

我预期是，视频在播放的时候，会频繁的触发 timeupdate 时间，然后用户操作的时候会频繁触发 handleChange 事件以更新 startTime 和 endTime, 我期望可以在 timeupdate 的handler 中，获取到最新的值。发现始终都是 0

这种情况，是由 React 的闭包特性和状态更新的异步性质导致的。

闭包问题：
当你创建 handleTimeupdate 函数时，它捕获了当时的 startTime 和 endTime 值。即使你后来通过 setStartTime 和 setEndTime 更新了这些状态，handleTimeupdate 函数仍然引用的是旧的值。
异步状态更新：
React 的状态更新是异步的。当你调用 setStartTime 和 setEndTime 时，状态并不会立即更新。

解决这个问题有几种方法：

使用 useRef 来存储这些值：

const startTimeRef = useRef(0)
const endTimeRef = useRef(0)

// 更新时
function updateTimes(start, end) {
  startTimeRef.current = start
  endTimeRef.current = end
  setStartTime(start)
  setEndTime(end)
}

// 在 handleTimeupdate 中
function handleTimeupdate() {
  console.log('videoRef.current.currentTime', videoRef.current.currentTime, 'startTime: ', startTimeRef.current, 'endTime:', endTimeRef.current)
  // ...
}copy success

使用函数式更新和 useCallback：

const handleTimeupdate = useCallback(() => {
  console.log('videoRef.current.currentTime', videoRef.current.currentTime, 'startTime: ', startTime, 'endTime:', endTime)
  // ...
}, [startTime, endTime])

useEffect(() => {
  // ... 其他代码 ...
  video.addEventListener('timeupdate', handleTimeupdate)
  return () => {
    video.removeEventListener('timeupdate', handleTimeupdate)
  }
}, [handleTimeupdate])copy success

直接在事件处理函数中访问最新的状态：

function handleTimeupdate() {
  console.log('videoRef.current.currentTime', videoRef.current.currentTime, 'startTime: ', startTimeRef.current, 'endTime:', endTimeRef.current)
  // 使用 getter 函数获取最新状态
  const currentStartTime = getStartTime()
  const currentEndTime = getEndTime()
  // ...
}copy success

使用 useEffect 监听 startTime 和 endTime 的变化：

useEffect(() => {
  const handleTimeupdate = () => {
    console.log('videoRef.current.currentTime', videoRef.current.currentTime, 'startTime: ', startTime, 'endTime:', endTime)
    // ...
  }

  const video = videoRef.current
  if (video) {
    video.addEventListener('timeupdate', handleTimeupdate)
    return () => video.removeEventListener('timeupdate', handleTimeupdate)
  }
}, [startTime, endTime])copy success

这些方法中，我个人推荐使用第一种（useRef）或第二种（useCallback）方法，因为它们既能解决问题，又不会导致过多的重渲染。

在父组件中获取子组件 A 中的 video 元素的 ref

SunZhongyi — Wed, 02 Aug 2023 00:00:00 GMT

记一次开发问题：

我有一组件A ，如下

// ......
  return (
    <div className="relative w-full max-w-[1000px] mx-auto">
      <video
// ......
copy success

现在我在父组件中，需要获取到这个 A 组件中的 video 元素的 ref，我可以怎么做呢？

要在父组件中获取子组件 A 中的 video 元素的 ref，你可以使用 React 的 forwardRef 和 useImperativeHandle 钩子。这里是一个步骤详解:

在子组件 A 中使用 forwardRef 并通过 useImperativeHandle 暴露 video 元素的 ref:

import React, { forwardRef, useImperativeHandle, useRef } from 'react'

const ComponentA = forwardRef((props, ref) => {
  const videoRef = useRef(null)

  useImperativeHandle(ref, () => ({
    videoElement: videoRef.current
  }))

  return (
    <div className="relative w-full max-w-[1000px] mx-auto">
      <video ref={videoRef} {...props} />
    </div>
  )
})

export default ComponentAcopy success

在父组件中，创建一个 ref 并将其传递给子组件 A:

import React, { useEffect, useRef } from 'react'
import ComponentA from './ComponentA'

function ParentComponent() {
  const componentARef = useRef(null)

  useEffect(() => {
    if (componentARef.current) {
      const videoElement = componentARef.current.videoElement
      // 现在你可以使用 videoElement 了
      console.log(videoElement)
    }
  }, [])

  return (
    <div>
      <ComponentA ref={componentARef} />
    </div>
  )
}

export default ParentComponentcopy success

通过这种方式，你可以在父组件中访问子组件 A 中的 video 元素。

要解释一下这个方法：

forwardRef 允许子组件接收父组件传递的 ref。
useImperativeHandle 允许你自定义暴露给父组件的实例值。在这个例子中，我们暴露了 video 元素的 ref。
在父组件中，我们创建了一个 ref（componentARef），并将其传递给 ComponentA。
然后，我们可以通过 componentARef.current.videoElement 来访问 video 元素。

这种方法保持了良好的组件封装，同时允许父组件在需要时访问子组件的特定 DOM 元素。

JavaScript中的事件循环

SunZhongyi — Tue, 08 Aug 2023 00:00:00 GMT

一、简述 JavaScript 中的事件循环(even loop) 是什么？

本文翻译自 link

event loop 是 Javascript 异步编程背后的奥秘，JS 执行所有的操作都是 单线程，但是利用一些小聪明的数据结构，能够给我们一些多线程操作的错觉。让我们看看在这背后发生了什么？

调用栈 (call stack)

**call stack ** 负责跟踪待执行的所有操作。每当一个函数执行完毕，它就会从栈中弹出。

事件队列（event queue）

event queue 负责将新的函数发送到 调用栈 进行处理，它遵循队列数据结构，以维护将所有操作发送到执行的正确顺序。

无论何时，当一个异步函数被调用的时候，它将会被发送到浏览器的API, 这些 API 是浏览器内置的，基于来自 call stack 的指令，这些 API 开始他们自己的单线程操作。

setTimeout 方法是一个很好的例子，当在 call stack 中执行一个 setTimeout 操作时，它将会被发送到对应的 API, 该 API 等待指定的时间后将此操作发送回进行处理。

那它将会把该操作发送到哪里呢？ —— event queue, 由此来看，在 Javascript 我们有一个循环系统，去执行异步操作。该语言本身是单线程的，但是浏览器的 APIS 都是多个独立的线程。

那 event loop 呢？ event loop 促使了这整个过程，它会不断的检查，当前调用栈是否为空，如果为空，新的 functions，就会从事件队列中添加进来，否则，当前 function 的调用就处理完毕了。

总结

总结的来说，当谈及 event loop 的时候，我们不能单独去思考，因为它是 JavaScript 异步编程中的一环。在描述一个概念时，要从 WWH (what-why-how) 思考框架去阐述。

What : Event loop 是 JavaScript 异步编程中的一个概念， JavaScript 是一个单线程的语言，通过异步编程的思想，能够让 JavaScript 模拟出多线程操作的效率。
Why : Event loop 是一个非常必要的机制，它保证了事件能够被按照正确的顺序处理，是整个异步函数调用的枢纽。负责管理调用栈和事件队列之间的交互。
How : ** 当一个异步函数被调用栈**所调用时，会被发送到浏览器对应的API 去执行，当异步操作执行完毕的时候，浏览器会将回调添加到 事件队列， 事件循环 会不断检查当前调用栈是否为空，如果为空就从事件队列的顶部取出一个事件放入到调用栈中去执行。在这个过程中， Event loop 事件循环起到一个连接闭环的作用。

补充说明，以 setTimeout 为例，当调用栈遇到该方法的时候，会发送到浏览器对应的 api, 然后等待指定时间后，将回调又追加到事件队列尾部。 event loop 会在调用栈为空时，从事件队列中取出事件压入到调用栈，然后不断循环这个过程。

这也是为什么说 setTimeout 无法做到完全准确的原因，实际上 setTimeout 的第二个参数指定的是执行回调的最小时间(最理想状态下, 事件队列前面为空，调用栈为空)

如何将含text的svg图转换为pathSvg（svg转曲）

SunZhongyi — Tue, 14 Nov 2023 00:00:00 GMT

工作业务中，使用到了 JsBarcode 用于生成条码图，但是直接生成的条码图如果为 svg 格式的话，存在一些问题：

字体丢失
无法旋转条码，我们需求它支持旋转
生成的svg 条码图中的文字部分直接是 <text> 元素，未转曲。

为了解决这个问题，我的解决思路是:

条码生成的时候插入base64格式的字体文件到 style 标签，追加到生成的svgNode
绘制一个背景塞入
将生成的svg绘制到 canvas，在canvas 上旋转
将canvas 通过位图转矢量图转换未转曲后的携带path 的 svg。

下面的演示仅包含关键逻辑代码，并非完整代码

一、追加字体文件到svg，修复生成的svg条码字体丢失问题：

......
// 创建svg节点，用于绘制 svg 条码
const svgNode = document.createElementNS(svgNS, "svg")

// 下面两行代码是因为我这边支持 png 和 svg 导出两种格式， 这边仅演示 options.export !== 'png' 的情况
const canvasNode = document.createElement("canvas")
const node = options.export === 'png' ? canvasNode : svgNode

// 使用 JSBarcode 绘制
JsBarcode(node, code, {
    textPosition: textPosition,
    format: options.symbology,
    lineColor: "#000",
    height: 40,
    margin: 20,
    font: "ocrb",
    //!需要本地指定 fontfaze https://github.com/lindell/JsBarcode/wiki/Options#font
    // 这里的 font 指定，在生成png格式(直接绘制到canvas)的时候，是正常的
    displayValue: true,
    background: '#FFFFFF'
});copy success

修复字体：

// @/assets/fonts/ocrb.base64
// base64 字体文件
export default "data:@file/x-font-ttf;base64,AAEAAAAOAIAAAwBgT1MvMoikfiEAAFAIAAAAVlBDTFR........copy success

import ocrbfont from "@/assets/fonts/ocrb.base64"

fixFont(svgNode)
const fixFont = (svgNode: SVGSVGElement)=>{
    const style = document.createElementNS("http://www.w3.org/2000/svg", "style");
    style.textContent = `
    @font-face {
        font-family: "ocrb";
        src: url('${ocrbfont}');
      }
    `
    svgNode.append(style)
}copy success

修复后的 svgNode 输出转未 xmlString，方便我们后续处理：

const xml = new XMLSerializer().serializeToString(svgNode)copy success

二、支持旋转并转曲

JsBarcode 支持条码和文字的上下倒置，但是不支持旋转，

所谓旋转，其实就是把条码竖过来，所有符合规则的条码如下图所示：

所以我们只要判断什么收竖直排列条码就可以了，至于文字如何排列可以在 jsBarcode 绘制阶段就能处理好，也就是上面的 textPosition 字段。

如何完成旋转呢？我们可以在canvas 上做到。

另一个问题是怎么将文字转为 path ？这里经过一番调研，请教有经验的同事，我知道了一个工具，叫做 Potrace, 这是一个位图转矢量图的工具，也就是你喂给它 png/jpeg之类的非矢量图，它会自动帮你转为 svg path，我们在web上使用，这里有一个 wasm 对应的库 potrace-wasm (直呼大佬nb!!! 大佬救我狗命！)

一番bug之后，我写了一个工具函数，如下：

├── convertNormalSvg2Path
│   ├── convertCanvas2Svg.ts
│   └── index.tscopy success

// convertCanvas2Svg.ts
import { loadFromCanvas } from "potrace-wasm";
export default (canvas: HTMLCanvasElement, config?: { [x: string]: any }) => {
    return new Promise((resolve, reject) => {
        loadFromCanvas(canvas, config)
            .then((svg:string) => resolve(svg))
            .catch((err:Error) => reject(err));
    })
}copy success

// index.ts
import convertCanvas2Svg from "./convertCanvas2Svg"
/**
 * svgxml: svgXml 字符串
 * scale: 放大倍数,值越大，转换结果越大，在容器固定时就会越清晰
 * isVertical: 横向/竖向
 */

export default (svgxml: string, scale: number = 2, isVertical: boolean):Promise<string> => {
    return new Promise((resolve, reject) => {
        const svgDoc = svgStr2Dom(svgxml)
        // 移除 svg 节点的 transform 属性
        svgDoc.removeAttribute('transform')
        const _svgxml = svgDom2Str(svgDoc)

        const url = 'data:image/svg+xml;charset=utf-8,' + encodeURIComponent(_svgxml);
        const img = new Image();
        img.src = url
        img.onload = async () => {
            if (svgDoc) {
                // 创建一个虚拟的 canvas 画布
                const canvas = document.createElement('canvas');
                // 按照指定规则绘制画布
                drawImg(canvas, svgDoc, img, isVertical, scale)
                try{
                    const newSvgXml = await convertCanvas2Svg(canvas) as string
                    resolve(newSvgXml)
                }catch(err){
                    reject(err)
                }
            }
        }
    })

}

// 设定画布信息
function setCanvas(canvas: HTMLCanvasElement, svgDoc: SVGElement, isVertical: boolean, scale: number) {
    const _width = svgDoc.getAttribute('width');
    const _height = svgDoc.getAttribute('height');
    if (_width && _height) {
        const width = parseInt(_width)
        const height = parseInt(_height)
        canvas.width = isVertical ? height * scale : width * scale
        canvas.height = isVertical ? width * scale : height * scale
    }
}

function drawImg(canvas: HTMLCanvasElement, svgDoc: SVGElement, img: HTMLImageElement, isVertical: boolean, scale: number) {
    setCanvas(canvas, svgDoc, isVertical, scale)
    const ctx = canvas.getContext('2d')
    if (!ctx) return
    ctx.scale(scale, scale);

    if (isVertical) {
        ctx.translate(img.height, 0);
        ctx.rotate((90 * Math.PI) / 180);
    }

    ctx.drawImage(img, 0, 0)
}

function svgDom2Str(svgElement: SVGElement) {
    const serializer = new XMLSerializer();
    // 使用 serializeToString 方法将 DOM 元素序列化为 XML 字符串
    return serializer.serializeToString(svgElement);
}
function svgStr2Dom(svgStr: string) {
    const parser = new DOMParser();
    return parser.parseFromString(svgStr, 'image/svg+xml').firstChild as SVGElement;
}copy success

如下调用：

const isVertical = ['left', 'right'].includes(options.position)
const _xml = await convertNormalSvg2Path(xml, 10, isVertical)copy success

特别注意第二个参数，他是基于输入xml 的 <svg height="xx" width="xx"> 的宽高的放大倍数，这个值越大，那么在canvas 上的绘制图也就越大，喂给 potrace-wasm 之后，输出的精度就越高，当然输出的 svg 尺寸也会更大。这个值太小就会失真，就像这样

三、额外的问题: 转曲后的svg 背景丢失了

这个问题好解决，我们自己画一个背景就行了：

+ import setBgc4PathSvg from "@/utils/setBgc4PathSvg"
.....
const isVertical = ['left', 'right'].includes(options.position)
const _xml = await convertNormalSvg2Path(xml, 10, isVertical)
+ const _xml_with_bgc = setBgc4PathSvg(_xml, '#FFFFFF')
copy success

// @/utils/setBgc4PathSvg.ts
export default function setBackgroundColor(xml: string, color: string) {
    const parser = new DOMParser();
    const xmlDoc = parser.parseFromString(xml, 'image/svg+xml').lastChild as SVGElement;
    // 获取元素宽高
    const svgHeight = xmlDoc.getAttribute("height")!;
    const svgWidth = xmlDoc.getAttribute("width")!;
    console.log('svgHeight', svgHeight)
    // 绘制一个矩形背景
    const rect = document.createElementNS("http://www.w3.org/2000/svg", "rect");
    rect.setAttribute("x", '0');
    rect.setAttribute("y", '0');
    rect.setAttribute("xmlns", "http://www.w3.org/2000/svg");
    rect.setAttribute("width", Number(svgWidth).toFixed());
    rect.setAttribute("height", Number(svgHeight).toFixed());
    rect.setAttribute("fill", color);

    // 将矩形元素添加到 SVG 中
    // 获取svg节点下面的第一个元素
    const firstChild = xmlDoc.firstChild;
    // 将举行边框插入到第一个元素之前
    xmlDoc.insertBefore(rect, firstChild);

    // 返回 xmlstring
    const serializer = new XMLSerializer();
    return serializer.serializeToString(xmlDoc);
}copy success

完美！

如何将含text的svg图转换为pathSvg（svg转曲）

SunZhongyi — Tue, 14 Nov 2023 00:00:00 GMT

工作业务中，使用到了 JsBarcode 用于生成条码图，但是直接生成的条码图如果为 svg 格式的话，存在一些问题：

字体丢失
无法旋转条码，我们需求它支持旋转
生成的svg 条码图中的文字部分直接是 <text> 元素，未转曲。

为了解决这个问题，我的解决思路是:

条码生成的时候插入base64格式的字体文件到 style 标签，追加到生成的svgNode
绘制一个背景塞入
将生成的svg绘制到 canvas，在canvas 上旋转
将canvas 通过位图转矢量图转换未转曲后的携带path 的 svg。

下面的演示仅包含关键逻辑代码，并非完整代码

一、追加字体文件到svg，修复生成的svg条码字体丢失问题：

......
// 创建svg节点，用于绘制 svg 条码
const svgNode = document.createElementNS(svgNS, "svg")

// 下面两行代码是因为我这边支持 png 和 svg 导出两种格式， 这边仅演示 options.export !== 'png' 的情况
const canvasNode = document.createElement("canvas")
const node = options.export === 'png' ? canvasNode : svgNode

// 使用 JSBarcode 绘制
JsBarcode(node, code, {
    textPosition: textPosition,
    format: options.symbology,
    lineColor: "#000",
    height: 40,
    margin: 20,
    font: "ocrb",
    //!需要本地指定 fontfaze https://github.com/lindell/JsBarcode/wiki/Options#font
    // 这里的 font 指定，在生成png格式(直接绘制到canvas)的时候，是正常的
    displayValue: true,
    background: '#FFFFFF'
});copy success

修复字体：

// @/assets/fonts/ocrb.base64
// base64 字体文件
export default "data:@file/x-font-ttf;base64,AAEAAAAOAIAAAwBgT1MvMoikfiEAAFAIAAAAVlBDTFR........copy success

import ocrbfont from "@/assets/fonts/ocrb.base64"

fixFont(svgNode)
const fixFont = (svgNode: SVGSVGElement)=>{
    const style = document.createElementNS("http://www.w3.org/2000/svg", "style");
    style.textContent = `
    @font-face {
        font-family: "ocrb";
        src: url('${ocrbfont}');
      }
    `
    svgNode.append(style)
}copy success

修复后的 svgNode 输出转未 xmlString，方便我们后续处理：

const xml = new XMLSerializer().serializeToString(svgNode)copy success

二、支持旋转并转曲

JsBarcode 支持条码和文字的上下倒置，但是不支持旋转，

所谓旋转，其实就是把条码竖过来，所有符合规则的条码如下图所示：

所以我们只要判断什么收竖直排列条码就可以了，至于文字如何排列可以在 jsBarcode 绘制阶段就能处理好，也就是上面的 textPosition 字段。

如何完成旋转呢？我们可以在canvas 上做到。

一番bug之后，我写了一个工具函数，如下：

├── convertNormalSvg2Path
│   ├── convertCanvas2Svg.ts
│   └── index.tscopy success

// convertCanvas2Svg.ts
import { loadFromCanvas } from "potrace-wasm";
export default (canvas: HTMLCanvasElement, config?: { [x: string]: any }) => {
    return new Promise((resolve, reject) => {
        loadFromCanvas(canvas, config)
            .then((svg:string) => resolve(svg))
            .catch((err:Error) => reject(err));
    })
}copy success

// index.ts
import convertCanvas2Svg from "./convertCanvas2Svg"
/**
 * svgxml: svgXml 字符串
 * scale: 放大倍数,值越大，转换结果越大，在容器固定时就会越清晰
 * isVertical: 横向/竖向
 */

export default (svgxml: string, scale: number = 2, isVertical: boolean):Promise<string> => {
    return new Promise((resolve, reject) => {
        const svgDoc = svgStr2Dom(svgxml)
        // 移除 svg 节点的 transform 属性
        svgDoc.removeAttribute('transform')
        const _svgxml = svgDom2Str(svgDoc)

        const url = 'data:image/svg+xml;charset=utf-8,' + encodeURIComponent(_svgxml);
        const img = new Image();
        img.src = url
        img.onload = async () => {
            if (svgDoc) {
                // 创建一个虚拟的 canvas 画布
                const canvas = document.createElement('canvas');
                // 按照指定规则绘制画布
                drawImg(canvas, svgDoc, img, isVertical, scale)
                try{
                    const newSvgXml = await convertCanvas2Svg(canvas) as string
                    resolve(newSvgXml)
                }catch(err){
                    reject(err)
                }
            }
        }
    })

}

// 设定画布信息
function setCanvas(canvas: HTMLCanvasElement, svgDoc: SVGElement, isVertical: boolean, scale: number) {
    const _width = svgDoc.getAttribute('width');
    const _height = svgDoc.getAttribute('height');
    if (_width && _height) {
        const width = parseInt(_width)
        const height = parseInt(_height)
        canvas.width = isVertical ? height * scale : width * scale
        canvas.height = isVertical ? width * scale : height * scale
    }
}

function drawImg(canvas: HTMLCanvasElement, svgDoc: SVGElement, img: HTMLImageElement, isVertical: boolean, scale: number) {
    setCanvas(canvas, svgDoc, isVertical, scale)
    const ctx = canvas.getContext('2d')
    if (!ctx) return
    ctx.scale(scale, scale);

    if (isVertical) {
        ctx.translate(img.height, 0);
        ctx.rotate((90 * Math.PI) / 180);
    }

    ctx.drawImage(img, 0, 0)
}

function svgDom2Str(svgElement: SVGElement) {
    const serializer = new XMLSerializer();
    // 使用 serializeToString 方法将 DOM 元素序列化为 XML 字符串
    return serializer.serializeToString(svgElement);
}
function svgStr2Dom(svgStr: string) {
    const parser = new DOMParser();
    return parser.parseFromString(svgStr, 'image/svg+xml').firstChild as SVGElement;
}copy success

如下调用：

const isVertical = ['left', 'right'].includes(options.position)
const _xml = await convertNormalSvg2Path(xml, 10, isVertical)copy success

特别注意第二个参数，他是基于输入xml 的 <svg height="xx" width="xx"> 的宽高的放大倍数，这个值越大，那么在canvas 上的绘制图也就越大，喂给 potrace-wasm 之后，输出的精度就越高，当然输出的 svg 尺寸也会更大。这个值太小就会失真，就像这样

三、额外的问题: 转曲后的svg 背景丢失了

这个问题好解决，我们自己画一个背景就行了：

+ import setBgc4PathSvg from "@/utils/setBgc4PathSvg"
.....
const isVertical = ['left', 'right'].includes(options.position)
const _xml = await convertNormalSvg2Path(xml, 10, isVertical)
+ const _xml_with_bgc = setBgc4PathSvg(_xml, '#FFFFFF')
copy success

// @/utils/setBgc4PathSvg.ts
export default function setBackgroundColor(xml: string, color: string) {
    const parser = new DOMParser();
    const xmlDoc = parser.parseFromString(xml, 'image/svg+xml').lastChild as SVGElement;
    // 获取元素宽高
    const svgHeight = xmlDoc.getAttribute("height")!;
    const svgWidth = xmlDoc.getAttribute("width")!;
    console.log('svgHeight', svgHeight)
    // 绘制一个矩形背景
    const rect = document.createElementNS("http://www.w3.org/2000/svg", "rect");
    rect.setAttribute("x", '0');
    rect.setAttribute("y", '0');
    rect.setAttribute("xmlns", "http://www.w3.org/2000/svg");
    rect.setAttribute("width", Number(svgWidth).toFixed());
    rect.setAttribute("height", Number(svgHeight).toFixed());
    rect.setAttribute("fill", color);

    // 将矩形元素添加到 SVG 中
    // 获取svg节点下面的第一个元素
    const firstChild = xmlDoc.firstChild;
    // 将举行边框插入到第一个元素之前
    xmlDoc.insertBefore(rect, firstChild);

    // 返回 xmlstring
    const serializer = new XMLSerializer();
    return serializer.serializeToString(xmlDoc);
}copy success

完美！

Docker Tips

SunZhongyi — Wed, 15 Nov 2023 00:00:00 GMT

命令	作用
docker ps	列出正在运行中的容器
docker ps -a	列出所有容器
docker images	列出所有本地镜像
docker rm [container1, ... , containerN]	删除一个或者多个容器
docker rmi [img1, ... ,imgN]	删除一个或者多个镜像
docker container prune	删除所有未被占用的(未运行的)容器
docker image prune	删除所有未被占用的(未运行的)镜像
docker run/stop	创建并启动某个容器/ 停止一个或者多个容器
docker pull/push	镜像拉取/推送到远程仓库
docker network ls	列出所有 Docker 网络
docker volume ls	列出所有 Docker 数据卷
docker stop $(docker ps -aq)	停止所有运行中的容器
docker rm $(docker ps -aq)	移除所有容器
docker rmi $(docker images -q)	移除所有镜像
docker system prune -a --volumes	清理未使用的资源

更多docker 相关指令见： https://docs.docker.com/reference/cli/docker/

命令	作用
docker-compose up	启动当前目录下的 docker-compose.yml 脚本
docker-compose up -d	后台启动
docker-compose down	停止并移除脚本中的容器、网络、卷和镜像。
docker-compose exec -it <container_name> /bin/bash	打开某个正在运行中的容器的shell窗口
docker-compose logs <container_name>	打印某个运行中的容器的日志
docker-compose logs -f <container_name>	实时监听某个运行中容器日志
docker-compose ps	列出在docker-compose.yml 中定义的服务
docker-compose build	使用 `Dockerfile` 或 `docker-compose.yml` 中的构建上下文重新构建服务
docker-compose stop	停止服务中的所有容器
docker-compose restart	重启服务中的所有容器
docker-compose rm	移除停止的容器

更多docker-compose 相关指令见：https://docs.docker.com/compose/reference/

Dockerfile 文档：https://docs.docker.com/reference/dockerfile/

Docker Compose File 文档： https://docs.docker.com/compose/compose-file/

检测图片是否cmyk

SunZhongyi — Sat, 18 Nov 2023 00:00:00 GMT

一、引入

最近业务上有要求，要求如果是 Jpeg 格式文件，前端在上传的时候要求判断一下这个文件是否 CMYK 颜色模式(color mode/ color space)。这个颜色模式是打印行业需要的。如果不是则禁止上传，并提示用户。

一开始我以为这个应该存储在 exif 文件信息中，去拿一下就好了，但是简单测试发现两个问题:

文件是否携带 exif 信息是不确定的，即便出自设计师导出文件，有可能也是不携带颜色模式信息的。
除此之外，依靠 exif 信息去判断，严格来说，即便携带，也是不准确的，因为这个信息是可以被人为修改的。

经过一番研究，我暂时发现可能有两种方式，去达成目的。但是这篇文章实际不是以解决问题为导向，而是期望尽可能的深入一丢丢。如果急于找到解决方案，直接翻到文章底部查看具体编码实现即可。

一、什么是 CMYK 颜色模式？

了解 Photoshop 颜色模式 (adobe.com)

CMYK 是一种颜色模式，它表示四种颜色通道：青色（Cyan）、品红色（Magenta）、黄色（Yellow）和黑色（Key，通常表示黑色）。这种颜色模式主要用于印刷和彩色印刷工作中。

以下是 CMYK 颜色模式中各颜色通道的简要介绍：

青色 (Cyan): 表示蓝绿色。在印刷中，它用于调整蓝色和绿色的浓度。
品红色 (Magenta): 表示品红或洋红色。在印刷中，它用于调整红色和蓝色的浓度。
黄色 (Yellow): 表示黄色。在印刷中，它用于调整红色和绿色的浓度。
黑色 (Key): 通常表示黑色。在印刷中，黑色是通过使用黑色油墨单独添加的，以增加图像的深度和对比度。在 CMYK 模式中，K 代表 Key，以避免与蓝色 (B) 冲突。

这四个颜色通道可以叠加在一起以创建各种颜色。通过调整每个通道的浓度，可以实现广泛的颜色表达。CMYK 被广泛用于印刷领域，因为它能够准确地模拟很多颜色，并提供了在印刷过程中需要的色彩控制。

与 RGB（红绿蓝）颜色模式不同，CMYK 是一种适合印刷的颜色模式，因为它更好地反映了油墨混合的方式，并考虑到印刷物质上的光的特性

二、怎么在web判断一个 jpeg/jpg 文件颜色模式是否 cmyk ?

简单说一下这两种方法，实际上是同一种原理，因为对于一张图片而言，它除了携带有 exif 文件元信息之外，还有文件头信息。

既然不能通过 exif 元信息去判断，那么我们可以通过文件头信息去做判断。

首先，简单测试可以发现，即便一个 cmyk 图片没有 exif 描述元信息标识这是一个 cmyk 颜色模式的图片，但是各种设计类软件都能够标记出来。以ps为例：

但是 exif 信息中是没有的：

甚至一些解析库，就连最基本携带的元信息都没读出来：

https://stackblitz.com/edit/exif-js-yk7nnb?file=ImageMega.js

为什么设计软件可以标记出这个图片是否是 cmyk 颜色模式？

这个问题，我在网上翻了很久，确实是找不到相关文章有阐述设计软件的原理。不过Ai 的回答是这样的，具备一定的参考性：

有朋友找到了记得踢我一脚，这里提前感谢啦~

三、用 ImageMagic 解析图片文件

什么是 imageMagic ?

ImageMagick 主要由大量的命令行程序组成，而不提供像 Adobe Photoshop、GIMP 这样的图形界面。它还为很多程序语言提供了 API 库。

ImageMagick 的功能包括：

查看、编辑位图文件

进行图像格式转换

图像特效处理

图像合成

图像批处理

ImageMagick 广泛用于图像处理、图形设计、Web 开发等领域。它是许多开源软件项目的重要组成部分，例如 GIMP、Inkscape、Linux 系统中的图像工具等。

ImageMagick 的优势包括：

功能强大，支持多种图像格式和图像处理功能

开放源代码，免费使用

、、可移植性强，支持多种操作系统

@jayce: imageMagic 类似于 ffmpeg, 只不过它专注图像处理

我们可以利用 ImageMagic 的 identify 工具命令去解析图片以查看一些信息：

加上 -verbose 选项可以查看更多详细信息：

$ ./magick identify -verbose ./CMYK.jpg
$ ./magick identify -verbose ./RGB.jpgcopy success

这些数据是什么？从哪里解析出来的呢？这个需要看一下 jpeg 文件的一些标准文件结构

四、ISO/IEC 10918-1 和 ISO/IEC 10918-5

这两个文件都是 JPEG 的标准文档，只是不同的部分，wiki 上对二者描述大致是 5 是对 1 的很多细节的展开和补充。是补充规范

JPEG File Interchange Format （JFIF）和 Exif

JFIF（JPEG File Interchange Format）和 EXIF（Exchangeable image file format）是两种与 JPEG 图像相关的标准，但它们具有不同的目的和功能。

JFIF 是一个图片文件格式标准，它被发布于 10918-5，是对 10918-1 的细节补充。

JFIF (JPEG File Interchange Format):
- 目的： JFIF 是一种用于在不同设备和平台之间交换 JPEG 图像的简单格式。它定义了 JPEG 文件的基本结构，以确保文件在不同系统中的一致性和可互操作性。
- 特点： JFIF 文件通常包含了基本的图像数据，但不一定包含元数据信息。它主要关注图像的编码和解码，而不太关心图像的其他详细信息。JFIF 文件通常使用 .jpg 或 .jpeg 扩展名。
EXIF (Exchangeable image file format):
- 目的： EXIF 是一种在数字摄影中广泛使用的标准，用于嵌入图像文件中的元数据信息。这些元数据可以包括拍摄日期、相机型号、曝光时间、光圈值等。EXIF 提供了更丰富的信息，有助于记录和存储与拍摄有关的详细数据。
- 特点： EXIF 数据以二进制格式嵌入在 JPEG 图像中，提供了关于图像和拍摄条件的详细信息。这对于数字相机和其他支持 EXIF 的设备非常有用。EXIF 文件通常使用 .jpg 或 .jpeg 扩展名。

五、JPEG 文件标准结构语法

jpeg 作为压缩数据结构，是一个非常复杂的数据组织，我们的关注点只在关系到我们想要解决的问题。标准文档 ISO/IEC 10918-1 : 1993(E).中有部分相关说明。

概要：

结构上来说， jpeg 的数据格式由以下几个部分，有序组成： parameters, markers, 以及 entropy-coded data segments, 其中 parameters 和 markers 部分通常被组织到 marker segments, 因为它们都是用字节对齐的代码表，都是由8位字节的有序序列组成。

Parameters

这部分携带有参数编码关键信息，是图片成功被解析的关键。

Markers

Markers 标记用于标识压缩数据格式的各种结构部分。大多数标记开始包含一组相关参数的标记段;有些标记是单独存在的。所有标记都被分配了两个字节的代码

例如 SOI : 从 0xFF,0xD8这两个字节开始，标记为图片文件的文件头开始， SOF0: 从 0xFF, 0xD8这两个字节开始，标记了 ”帧“ 的开始，它实际上会携带有图片的一些基本信息，例如宽高，以及颜色通道等。这个颜色通道其实也是我们主要需要关注的地方。

下表是完整的标记代码：

@refer:

https://www.digicamsoft.com/itu/itu-t81-35.html
https://www.digicamsoft.com/itu/itu-t81-36.html

wiki 上也有相关的帧头部字段说明：


Short name	Bytes	Payload	Name	Comments
SOI	0xFF, 0xD8	none	Start Of Image
SOF0	0xFF, 0xC0	variable size	Start Of Frame (baseline DCT)	Indicates that this is a baseline DCT-based JPEG, and specifies the width, height, number of components, and component subsampling (e.g., 4:2:0).
SOF2	0xFF, 0xC2	variable size	Start Of Frame (progressive DCT)	Indicates that this is a progressive DCT-based JPEG, and specifies the width, height, number of components, and component subsampling (e.g., 4:2:0).
DHT	0xFF, 0xC4	variable size	Define Huffman Table(s)	Specifies one or more Huffman tables.
DQT	0xFF, 0xDB	variable size	Define Quantization Table(s)	Specifies one or more quantization tables.
DRI	0xFF, 0xDD	4 bytes	Define Restart Interval	Specifies the interval between RSTn markers, in Minimum Coded Units (MCUs). This marker is followed by two bytes indicating the fixed size so it can be treated like any other variable size segment.
SOS	0xFF, 0xDA	variable size	Start Of Scan	Begins a top-to-bottom scan of the image. In baseline DCT JPEG images, there is generally a single scan. Progressive DCT JPEG images usually contain multiple scans. This marker specifies which slice of data it will contain, and is immediately followed by entropy-coded data.
RSTn	0xFF, 0xDn (n=0..7)	none	Restart	Inserted every r macroblocks, where r is the restart interval set by a DRI marker. Not used if there was no DRI marker. The low three bits of the marker code cycle in value from 0 to 7.
APPn	0xFF, 0xEn	variable size	Application-specific	For example, an Exif JPEG file uses an APP1 marker to store metadata, laid out in a structure based closely on TIFF.
COM	0xFF, 0xFE	variable size	Comment	Contains a text comment.
EOI	0xFF, 0xD9	none	End Of Image

Syntax and structure

整体结构

@refer: https://www.digicamsoft.com/itu/itu-t81-38.html

Frame Header

@refer: https://www.digicamsoft.com/itu/itu-t81-35.html

SOF_n : 帧开始标记标记帧参数的开始。下标n标识编码过程是基线顺序、扩展顺序、渐进还是无损，以及使用哪种熵编码过程。

在其标准文档中，我们有找到 SOF_n 的子字段说明，不过在其他地方，倒是看到了不少描述：

特别是在这里 JPEG File Layout and Format

可以看到，在 SOF_n 这个标记中，有一个字段为会指明 components 的数量，它代表的实际上颜色通道，如果是 1，那么就是灰度图，如果是3，那就是RGB，如果是 4 就是 CMYK.

到这里我们就知道了，我们可以读取到这个对应的字节段，从而判断一个图片的颜色模式了。

六、怎么读取呢？

这篇资料说了明了 Jpeg 文件格式中字节和上述字段的关联关系: Anatomy of a JPEG

注意这篇资料中有一段描述，会影响到我们后续的逻辑判断：

就是 SOF₀ 是必须的，但是可以被 SOF_n>=1 替换。所以在做逻辑判断的时候，后续的也要判断。

我们可以先大概看看一个图片文件的字节流数据长什么样子：(因为所有的字段都是 FF 字节位开头，所以高亮了)

以上页面可以在这里访问： https://joisun.github.io/demos/DemoPages/image_binary_render/dist/

但样太不便于阅读了，而且实在太长了。这里有个网站 here，可以将关键的字节段截取出来：

我们主要看这里：

可以看到 components 为 4.

如果是 RGB：

这里就是 3，

如果是灰度图，components 就会是1

EXIF 在哪里？

一个额外的小问题，我们常见的 exif 元信息存储在哪里呢？

其实上面的 Markers 部分给出的表格中也说明了，在 App_n 中可以找到 exif 信息，但是wiki 上说的是 App₀，在这个解析网站中，我们可以看到：

七、编码实现

有了上述具体的分析，我们就能有大致思路，这里直接给出相关代码：

代码参考 github.com/zengming00/node-jpg-is-cmyk


/**
 * @refer https://github.com/zengming00/node-jpg-is-cmyk/blob/master/src/index.ts
 * @refer https://cyber.meme.tips/jpdump/#
 * @refer https://mykb.cipindanci.com/archive/SuperKB/1294/JPEG%20File%20Layout%20and%20Format.htm
 * @refer https://www.ccoderun.ca/programming/2017-01-31_jpeg/
 *
 * 通过 jpg 文件头判断是否是 CMYK 颜色模式
 * @param { Uint8Array } data
 */
function checkCmyk(data: Uint8Array) {
    let pos = 0;
    while (pos < data.length) {
        pos++;
        switch (data[pos]) {
            case 0xd8: {// SOI - Start of Image
                pos++;
                break;
            }
            case 0xd9: {// EOI - End of Image
                pos++;
                break;
            }
            case 0xc0: // SOF0 - Start of Frame, Baseline DCT
            case 0xc1: // SOF1 - Start of Frame, Extended Sequential DCT
            case 0xc2: { // SOF2 - Start of Frame, Progressive DCT
                pos++;
                const len = (data[pos] << 8) | data[pos + 1];
                const compoNum = data[pos + 7];
                if (compoNum === 4) {
                    // 如果components 数量为4， 那么就认为是 cmyk
                    return true;
                }
                pos += len;
                break;
            }
            case 0xc4: { // DHT - Define Huffman Table
                pos++;
                const len = (data[pos] << 8) | data[pos + 1];
                pos += len;
                break;
            }
            case 0xda: { // SOS - Start of Scan
                pos++;
                const len = (data[pos] << 8) | data[pos + 1];
                pos += len;
                break;
            }
            case 0xdb: { // DQT - Define Quantization Table
                pos++;
                const len = (data[pos] << 8) | data[pos + 1];
                pos += len;
                break;
            }
            case 0xdd: { // DRI - Define Restart Interval
                pos++;
                const len = (data[pos] << 8) | data[pos + 1];
                pos += len;
                break;
            }
            case 0xe0: { // APP0 - Application-specific marker
                pos++;
                const len = (data[pos] << 8) | data[pos + 1];
                pos += len;
                break;
            }
            case 0xfe: { // COM - Comment
                pos++;
                const len = (data[pos] << 8) | data[pos + 1];
                pos += len;
                break;
            }
            default: {
                pos++;
                const len = (data[pos] << 8) | data[pos + 1];
                pos += len;
            }
        }
    }
    return false;
}copy success

八、有没有其他的方法？

既然 imageMagic 这么成熟且强大，我们有办法利用它来做判断吗？

我们可以通过 wasm，在web中去利用这些工具，我找到了 WASM-ImageMagick 这个，但是他的打包好像有些问题 vite 引入的时候会报错，看着好像也没有要修复的意思， issue 里面有老哥自己修改了打包配置进行了修复在这里: image-magick

我们就写的demo测试函数：

import * as Magick from '@xn-sakina/image-magick'

export default function (file: File) {
    if (!file) return;
    // 创建FileReader对象
    var reader = new FileReader();
    // 当读取完成时的回调函数
    reader.onload = async function (e) {
        // 获取ArrayBuffer
        var arrayBuffer = e.target?.result as ArrayBuffer;
        if (arrayBuffer) {
            // 将 ArrayBuffer 转换为 Uint8Array
            const sourceBytes = new Uint8Array(arrayBuffer);
            const inputFiles = [{ name: 'srcFile.png', content: sourceBytes }]
            let commands: string[] = ["identify srcFile.png"]
            const { stdout } = await Magick.execute({inputFiles, commands});

            // 这里打印一下结果
            console.log('stdout:',stdout[0])

        }
    };
    // 读取文件为ArrayBuffer
    reader.readAsArrayBuffer(file);
}copy success

import isCmyk from '../utils/isCmyk.ts'
const handleFileChange = (e: Event) => {
    const file = (e.target as HTMLInputElement)?.files?.[0]
	isCmyk(file) // 这里文件上传调用一下
......copy success

测试几个文件

可以看到， Gray, RGB, CMYK 检测都可以正常输出，说明可以这么干。

但是这个库，文档写的太乱了。 - -

这个库的大小有 5 m之大 - -， npm 上找了下，目前相关的包，也没有比这个更小的好像。

检测图片是否cmyk

SunZhongyi — Sat, 18 Nov 2023 00:00:00 GMT

一、引入

一开始我以为这个应该存储在 exif 文件信息中，去拿一下就好了，但是简单测试发现两个问题:

文件是否携带 exif 信息是不确定的，即便出自设计师导出文件，有可能也是不携带颜色模式信息的。
除此之外，依靠 exif 信息去判断，严格来说，即便携带，也是不准确的，因为这个信息是可以被人为修改的。

一、什么是 CMYK 颜色模式？

了解 Photoshop 颜色模式 (adobe.com)

以下是 CMYK 颜色模式中各颜色通道的简要介绍：

青色 (Cyan): 表示蓝绿色。在印刷中，它用于调整蓝色和绿色的浓度。
品红色 (Magenta): 表示品红或洋红色。在印刷中，它用于调整红色和蓝色的浓度。
黄色 (Yellow): 表示黄色。在印刷中，它用于调整红色和绿色的浓度。
黑色 (Key): 通常表示黑色。在印刷中，黑色是通过使用黑色油墨单独添加的，以增加图像的深度和对比度。在 CMYK 模式中，K 代表 Key，以避免与蓝色 (B) 冲突。

与 RGB（红绿蓝）颜色模式不同，CMYK 是一种适合印刷的颜色模式，因为它更好地反映了油墨混合的方式，并考虑到印刷物质上的光的特性

二、怎么在web判断一个 jpeg/jpg 文件颜色模式是否 cmyk ?

简单说一下这两种方法，实际上是同一种原理，因为对于一张图片而言，它除了携带有 exif 文件元信息之外，还有文件头信息。

既然不能通过 exif 元信息去判断，那么我们可以通过文件头信息去做判断。

但是 exif 信息中是没有的：

甚至一些解析库，就连最基本携带的元信息都没读出来：

https://stackblitz.com/edit/exif-js-yk7nnb?file=ImageMega.js

为什么设计软件可以标记出这个图片是否是 cmyk 颜色模式？

这个问题，我在网上翻了很久，确实是找不到相关文章有阐述设计软件的原理。不过Ai 的回答是这样的，具备一定的参考性：

有朋友找到了记得踢我一脚，这里提前感谢啦~

三、用 ImageMagic 解析图片文件

什么是 imageMagic ?

ImageMagick 主要由大量的命令行程序组成，而不提供像 Adobe Photoshop、GIMP 这样的图形界面。它还为很多程序语言提供了 API 库。

ImageMagick 的功能包括：

查看、编辑位图文件

进行图像格式转换

图像特效处理

图像合成

图像批处理

ImageMagick 广泛用于图像处理、图形设计、Web 开发等领域。它是许多开源软件项目的重要组成部分，例如 GIMP、Inkscape、Linux 系统中的图像工具等。

ImageMagick 的优势包括：

功能强大，支持多种图像格式和图像处理功能

开放源代码，免费使用

、、可移植性强，支持多种操作系统

@jayce: imageMagic 类似于 ffmpeg, 只不过它专注图像处理

我们可以利用 ImageMagic 的 identify 工具命令去解析图片以查看一些信息：

加上 -verbose 选项可以查看更多详细信息：

$ ./magick identify -verbose ./CMYK.jpg
$ ./magick identify -verbose ./RGB.jpgcopy success

这些数据是什么？从哪里解析出来的呢？这个需要看一下 jpeg 文件的一些标准文件结构

四、ISO/IEC 10918-1 和 ISO/IEC 10918-5

这两个文件都是 JPEG 的标准文档，只是不同的部分，wiki 上对二者描述大致是 5 是对 1 的很多细节的展开和补充。是补充规范

JPEG File Interchange Format （JFIF）和 Exif

JFIF（JPEG File Interchange Format）和 EXIF（Exchangeable image file format）是两种与 JPEG 图像相关的标准，但它们具有不同的目的和功能。

JFIF 是一个图片文件格式标准，它被发布于 10918-5，是对 10918-1 的细节补充。

JFIF (JPEG File Interchange Format):
- 目的： JFIF 是一种用于在不同设备和平台之间交换 JPEG 图像的简单格式。它定义了 JPEG 文件的基本结构，以确保文件在不同系统中的一致性和可互操作性。
- 特点： JFIF 文件通常包含了基本的图像数据，但不一定包含元数据信息。它主要关注图像的编码和解码，而不太关心图像的其他详细信息。JFIF 文件通常使用 .jpg 或 .jpeg 扩展名。
EXIF (Exchangeable image file format):
- 目的： EXIF 是一种在数字摄影中广泛使用的标准，用于嵌入图像文件中的元数据信息。这些元数据可以包括拍摄日期、相机型号、曝光时间、光圈值等。EXIF 提供了更丰富的信息，有助于记录和存储与拍摄有关的详细数据。
- 特点： EXIF 数据以二进制格式嵌入在 JPEG 图像中，提供了关于图像和拍摄条件的详细信息。这对于数字相机和其他支持 EXIF 的设备非常有用。EXIF 文件通常使用 .jpg 或 .jpeg 扩展名。

五、JPEG 文件标准结构语法

概要：

Parameters

这部分携带有参数编码关键信息，是图片成功被解析的关键。

Markers

下表是完整的标记代码：

@refer:

https://www.digicamsoft.com/itu/itu-t81-35.html
https://www.digicamsoft.com/itu/itu-t81-36.html

wiki 上也有相关的帧头部字段说明：


Short name	Bytes	Payload	Name	Comments
SOI	0xFF, 0xD8	none	Start Of Image
SOF0	0xFF, 0xC0	variable size	Start Of Frame (baseline DCT)	Indicates that this is a baseline DCT-based JPEG, and specifies the width, height, number of components, and component subsampling (e.g., 4:2:0).
SOF2	0xFF, 0xC2	variable size	Start Of Frame (progressive DCT)	Indicates that this is a progressive DCT-based JPEG, and specifies the width, height, number of components, and component subsampling (e.g., 4:2:0).
DHT	0xFF, 0xC4	variable size	Define Huffman Table(s)	Specifies one or more Huffman tables.
DQT	0xFF, 0xDB	variable size	Define Quantization Table(s)	Specifies one or more quantization tables.
DRI	0xFF, 0xDD	4 bytes	Define Restart Interval	Specifies the interval between RSTn markers, in Minimum Coded Units (MCUs). This marker is followed by two bytes indicating the fixed size so it can be treated like any other variable size segment.
SOS	0xFF, 0xDA	variable size	Start Of Scan	Begins a top-to-bottom scan of the image. In baseline DCT JPEG images, there is generally a single scan. Progressive DCT JPEG images usually contain multiple scans. This marker specifies which slice of data it will contain, and is immediately followed by entropy-coded data.
RSTn	0xFF, 0xDn (n=0..7)	none	Restart	Inserted every r macroblocks, where r is the restart interval set by a DRI marker. Not used if there was no DRI marker. The low three bits of the marker code cycle in value from 0 to 7.
APPn	0xFF, 0xEn	variable size	Application-specific	For example, an Exif JPEG file uses an APP1 marker to store metadata, laid out in a structure based closely on TIFF.
COM	0xFF, 0xFE	variable size	Comment	Contains a text comment.
EOI	0xFF, 0xD9	none	End Of Image

Syntax and structure

整体结构

@refer: https://www.digicamsoft.com/itu/itu-t81-38.html

Frame Header

@refer: https://www.digicamsoft.com/itu/itu-t81-35.html

SOF_n : 帧开始标记标记帧参数的开始。下标n标识编码过程是基线顺序、扩展顺序、渐进还是无损，以及使用哪种熵编码过程。

在其标准文档中，我们有找到 SOF_n 的子字段说明，不过在其他地方，倒是看到了不少描述：

特别是在这里 JPEG File Layout and Format

到这里我们就知道了，我们可以读取到这个对应的字节段，从而判断一个图片的颜色模式了。

六、怎么读取呢？

这篇资料说了明了 Jpeg 文件格式中字节和上述字段的关联关系: Anatomy of a JPEG

注意这篇资料中有一段描述，会影响到我们后续的逻辑判断：

就是 SOF₀ 是必须的，但是可以被 SOF_n>=1 替换。所以在做逻辑判断的时候，后续的也要判断。

我们可以先大概看看一个图片文件的字节流数据长什么样子：(因为所有的字段都是 FF 字节位开头，所以高亮了)

以上页面可以在这里访问： https://joisun.github.io/demos/DemoPages/image_binary_render/dist/

但样太不便于阅读了，而且实在太长了。这里有个网站 here，可以将关键的字节段截取出来：

我们主要看这里：

可以看到 components 为 4.

如果是 RGB：

这里就是 3，

如果是灰度图，components 就会是1

EXIF 在哪里？

一个额外的小问题，我们常见的 exif 元信息存储在哪里呢？

其实上面的 Markers 部分给出的表格中也说明了，在 App_n 中可以找到 exif 信息，但是wiki 上说的是 App₀，在这个解析网站中，我们可以看到：

七、编码实现

有了上述具体的分析，我们就能有大致思路，这里直接给出相关代码：

代码参考 github.com/zengming00/node-jpg-is-cmyk


/**
 * @refer https://github.com/zengming00/node-jpg-is-cmyk/blob/master/src/index.ts
 * @refer https://cyber.meme.tips/jpdump/#
 * @refer https://mykb.cipindanci.com/archive/SuperKB/1294/JPEG%20File%20Layout%20and%20Format.htm
 * @refer https://www.ccoderun.ca/programming/2017-01-31_jpeg/
 *
 * 通过 jpg 文件头判断是否是 CMYK 颜色模式
 * @param { Uint8Array } data
 */
function checkCmyk(data: Uint8Array) {
    let pos = 0;
    while (pos < data.length) {
        pos++;
        switch (data[pos]) {
            case 0xd8: {// SOI - Start of Image
                pos++;
                break;
            }
            case 0xd9: {// EOI - End of Image
                pos++;
                break;
            }
            case 0xc0: // SOF0 - Start of Frame, Baseline DCT
            case 0xc1: // SOF1 - Start of Frame, Extended Sequential DCT
            case 0xc2: { // SOF2 - Start of Frame, Progressive DCT
                pos++;
                const len = (data[pos] << 8) | data[pos + 1];
                const compoNum = data[pos + 7];
                if (compoNum === 4) {
                    // 如果components 数量为4， 那么就认为是 cmyk
                    return true;
                }
                pos += len;
                break;
            }
            case 0xc4: { // DHT - Define Huffman Table
                pos++;
                const len = (data[pos] << 8) | data[pos + 1];
                pos += len;
                break;
            }
            case 0xda: { // SOS - Start of Scan
                pos++;
                const len = (data[pos] << 8) | data[pos + 1];
                pos += len;
                break;
            }
            case 0xdb: { // DQT - Define Quantization Table
                pos++;
                const len = (data[pos] << 8) | data[pos + 1];
                pos += len;
                break;
            }
            case 0xdd: { // DRI - Define Restart Interval
                pos++;
                const len = (data[pos] << 8) | data[pos + 1];
                pos += len;
                break;
            }
            case 0xe0: { // APP0 - Application-specific marker
                pos++;
                const len = (data[pos] << 8) | data[pos + 1];
                pos += len;
                break;
            }
            case 0xfe: { // COM - Comment
                pos++;
                const len = (data[pos] << 8) | data[pos + 1];
                pos += len;
                break;
            }
            default: {
                pos++;
                const len = (data[pos] << 8) | data[pos + 1];
                pos += len;
            }
        }
    }
    return false;
}copy success

八、有没有其他的方法？

既然 imageMagic 这么成熟且强大，我们有办法利用它来做判断吗？

我们就写的demo测试函数：

import * as Magick from '@xn-sakina/image-magick'

export default function (file: File) {
    if (!file) return;
    // 创建FileReader对象
    var reader = new FileReader();
    // 当读取完成时的回调函数
    reader.onload = async function (e) {
        // 获取ArrayBuffer
        var arrayBuffer = e.target?.result as ArrayBuffer;
        if (arrayBuffer) {
            // 将 ArrayBuffer 转换为 Uint8Array
            const sourceBytes = new Uint8Array(arrayBuffer);
            const inputFiles = [{ name: 'srcFile.png', content: sourceBytes }]
            let commands: string[] = ["identify srcFile.png"]
            const { stdout } = await Magick.execute({inputFiles, commands});

            // 这里打印一下结果
            console.log('stdout:',stdout[0])

        }
    };
    // 读取文件为ArrayBuffer
    reader.readAsArrayBuffer(file);
}copy success

import isCmyk from '../utils/isCmyk.ts'
const handleFileChange = (e: Event) => {
    const file = (e.target as HTMLInputElement)?.files?.[0]
	isCmyk(file) // 这里文件上传调用一下
......copy success

测试几个文件

可以看到， Gray, RGB, CMYK 检测都可以正常输出，说明可以这么干。

但是这个库，文档写的太乱了。 - -

这个库的大小有 5 m之大 - -， npm 上找了下，目前相关的包，也没有比这个更小的好像。

Redux 指南

SunZhongyi — Sun, 14 Jan 2024 00:00:00 GMT

一、通过 CDN 示例快速认识 Redux

Redux 最简化使用步骤

定义一个 reducer 函数
使用 createStore 方法传入 reducer 函数，生成一个 store 实例对象
通过 store 实例的 dispatch 方法提交一个 action 对象触发数据变化
通过 store 实例的 subscribe 方法订阅数据变化
通过 store 实例的 getState 方法获取最新的状态数据更新到视图中

具体实例

<button class="w-12 mi border active:bg-black">-</button>
<span class="count mx-4">0</span>
<button class="w-12 add border active:bg-black">+</button>copy success

// main.ts

const miBtn = document.querySelector(".mi")
const addBtn = document.querySelector(".add")
const countEL = document.querySelector(".count") as HTMLSpanElement
import { createStore } from "https://unpkg.com/redux@5.0.1/dist/redux.browser.mjs"

// typings
enum ActionTypes {
    MINUS = "Increment",
    ADD = "Decrement"
}

/**
 * 1.定义 reducer 函数
 * @param state 管理的数据初始状态
 * @param action 对象type 标记当前的修改类型
 */
const countReducer = (state = { count: 0 }, action: { type: ActionTypes }) => {
    switch (action.type) {
        case ActionTypes.ADD:
            return { count: ++state.count }
        case ActionTypes.MINUS:
            return { count: --state.count }
        default:
            return state
    }
}

// 2.使用reducer函数生成 store 实例
const store = createStore(countReducer)

// 3.派发更新
const handleMinus = () => {
    store.dispatch({ type: ActionTypes.MINUS })
}
const handleAdd = () => {
    store.dispatch({ type: ActionTypes.ADD })
}

// 4.通过 store.subscribe 方法订阅 数据对象的变动
store.subscribe(() => {
    // 5.通过 getState 方法获取最新的状态数据
    const { count } = store.getState()
    countEL.innerText = count
})

miBtn?.addEventListener('click', handleMinus)
addBtn?.addEventListener('click', handleAdd)copy success

Redux 的应用逻辑

Redux 数据流图

https://redux.js.org/tutorials/fundamentals/part-2-concepts-data-flow#redux-application-data-flow

二、在 React 应用中使用 Redux

Redux 本省是框架无关的，在上面的 CDN 示例中，可以看到，原生 JS 也是可以直接使用的。但是其他的 UI 库如 React，有自己的渲染更新逻辑，所以需要在适当的实际触发 React 的 re-render 从而使得页面上更新新的数据。

在 React 中使用 Redux，官方提供了两个包： redux-toolkit 和 react-redux。

redux-toolkit(RTK): 这是官方推荐的编写 Redux 逻辑的方式，它是一套工具集，用以简化书写
1. 简化 store 的配置方式
2. 内置 immer 支持可变式状态修改
3. 内置 thunk 更好的异步创建

react-redux：用来链接 Redux 和 React 组件的中间件

graph LR
 A[React]-.-> C([react-redux])
 C -.-> A
 A -->|获取状态| B[React 组件]
 B -.-> C
 C -.-> B
 B -->|更新状态| A
copy success


### 在 React 应用中使用 Redux 示例
copy success

pnpm 版本管理

SunZhongyi — Thu, 01 Feb 2024 00:00:00 GMT

启用 corepack 管理

corepack enablecopy success

设定当前pnpm 版本

corepack prepare pnpm@7.13.6 --activate
corepack prepare pnpm@latest --activate
corepack prepare pnpm@latest-6 --activatecopy success

Git Tips

SunZhongyi — Mon, 05 Feb 2024 00:00:00 GMT

一、Hot Tips

说明	命令	示例
从本地推送并创建远程分支	`git push <远程主机名> <本地分支名>:<远程分支名>` 如果远程主机中没有对应的分支,则会新建该分支。	`git push sunzy dev:dev`
	也可以通过`-u`或`--set-upstream`选项设置关联关系,这样以后就可以直接使用`git push`来推送本地分支了: `git push -u origin dev` 此外,也可以使用`git push origin :dev`的方式删除远程的分支。
`--no-ff` 合并	`git merge` 和 `git merge --no-ff` 都是用来合并 branch 的命令，在使用上存在一些差异。 1.`git merge`：在默认情况下，Git执行"Fast-forward"模式，如果被合并的 branch 比当前的 branch 更新（在提交历史上在前），那么 Git 只会简单地把 HEAD 指针指向被合并的 branch，这就是快进（fast-forward）合并。这种方式下，合并的信息并不会体现在commit历史中。 2.`git merge --no-ff`：--no-ff参数意味着"no fast forward"，禁用"Fast-forward"模式。即使被合并的 branch 比当前的 branch 更新，Git 在合并时也会创建一个新的 commit 对象，并把两个 branch 的最新 commit 作为这个新 commit 的 parents。这样可以在历史记录中明确地看到分支与合并的情况，更清晰的保留项目历史和合并信息。在团队协作中，`git merge --no-ff` 更为推荐，因为这样可以清楚地看到项目的分支和合并历史。	`git merge <target branch> --no-ff -m "为合并这个操作附加一段commit msg"`
临时bug修复	有时候，突然接到一个紧急修复线上bug的任务，这时候肯定需要新建一个专用于修复bug的分支，但是当前分支上的工作还没有完成，或者不便于立即提交当前工作以保持工作的连续性。这时候我们可以使用 git 提供的暂存工作区的功能。 1. `git stash` 暂存当前工作区 2. `git stash list` 查看当前暂存的工作区 3.恢复工作区有两种方式，第一种是 `git stash apply`恢复，然后删除 stash，`git stash drop`; 另一种是直接恢复并删除stash, `git stash pop` 4. `git stash list` 是查看所有stash 的列表，意味着 `git stash` 可以多次执行，想要恢复到指定版本的stash , 可以这样 `git stash apply stash@{stash序号}`
cherry-pick	有时候，在某个分支上做了某些细微改动，但是当前在另一个分支上，例如我在主分支上提交了bug修复，当我当前在dev分支上，这个分支上也有这个bug没修复，这时候，可以直接把那个修复bug的commit复制过来，这个行为称为 `cherry-pick`	`git cherry-pick 4c805e2`, 后面的编号就是commit id
修改默认分支master为 main	1. 修改本地分支： `git branch -m master main` 2. 创建远程新分支main: `git push -u origin main` 3. 删除远程 master 分支：`git push origin --delete master` 其他人： 1. 切换到master 分支： `git checkout master` 2. 重命名为 main: `git branch -m master main` 3. 拉取最新commits和分支：`git fetch` 4. 移除远程追踪分支：`git branch --unset-upstream` 5. 创建新的对远程main分支的追踪： `git branch -u origin/main`

二、版本管理

说明	命令	示例
查看历史提交记录	`git log`
查看历史提交记录，单行显示	`git log --pretty=oneline`
将当前仓库回退到上个版本	`git reset --hard HEAD^`
将当前仓库回退到上上个版本	`git reset --hard HEAD^^`
将当前仓库回退到上 N 个版本	`git reset --hard HEAD~n`
将当前仓库指向到特定版本	`git reset --hard <commitId>`
如果回退到某个历史版本后，那么自该历史版本之后的新版本，通过 `git log` 命令就看不见了，这时候如果需要重新回到某个新的版本，需要知道对应的 commit id, 可以通过 git reflog 命令查找所有的版本变更记录，从而找到 commit id，然后使用 `reset` 命令就可以切换到指定版本	`git reflog`

三、撤销修改

说明	命令	示例
撤销当前工作区单文件修改	`git checkout -- <file>`
撤销删除，如果意外删除了某个文件，也可以用`checkout --` 命令恢复	`rm -f <file>` `git checkout -- <file>`
撤销当前工作区所有修改	`git checkout -- .`
撤销暂存区单文件修改, 注意撤销后的文件修改不会丢失，而是回到工作区，变成modified 状态	`git restore --staged <file>` 或者 `git reset HEAD <file>` 二者主要区别在于主要的区别在于`git restore --staged <file>`会恢复暂存区中的更改到工作目录中，而`git reset HEAD <file>`则是将暂存区中的文件状态重置为与最新提交相同，但不会影响工作目录中的文件。
撤销暂存区所有文件修改，注意撤销后的文件修改不会丢失，而是回到工作区，变成modified 状态	`git restore --staged .`

当确定删除某个文件后，需要 git add <file> 以暂存这个 “删除操作”，然后才能 commit, 这个操作等同于直接使用git rm 删除文件。

四、分支管理

说明	命令	示例
查看分支	`git branch`仅查看本地分支, `git branch -a`查看所有分支，包括远程分支
创建并切换分支	`git checkout -b <new branch name>`, 或者 `git switch -c <new branch name>`
切换分支	`git checkout <branch>`，或者 `git switch <branch>`
合并分支	`git merge <target branch>`, 将目标分支合并到当前分支
删除分支	`git branch -d <target branch>`
变基	`git rebase`
分支临时切换，工作区域暂存	主要通过 `git stash` 命令，将所有修改（包括已暂存和未暂存的内容）保存到暂存区，并清理当前工作目录。注意⚠️：该命令默认情况下，git stash 只保存已跟踪文件（tracked files）的修改，如果需要保存 untracked 文件的修改，需要加上 `--include-untracked` 或 `-u` 选项。 `git stash show` 命令可以查看当前保存的文件 `git stash pop` 将保存的文件弹出到当前工作区。最简单的操作流程是：当前分支在 feature-branch git stash --include-untracked：保存所有修改。 git checkout hotfix-branch：切换分支。处理完需求后，git checkout feature-branch。 git stash pop：恢复修改。

五、冲突管理

冲突发生在分支合并时，例如a,b 两个分支同时修改了同一个文件，在合并的时候就会产生冲突，冲突发生时，该目标文件会被修改。例如：
1 <<<<<<< HEAD
2 hello file02 world
3 =======
4 hello world file02
5 >>>>>>> newbranch
6 asdas
copy success
这时候，需要手动去修正这个文件，然后提交，就可以修复冲突。如果不修改，直接git add . 然后 commit, 那么这份冲突的文件就会被直接提交，包含这些 <<<<....,=== 表示冲突的标记。各类编辑器携带的冲突编辑器只是帮我们便捷处理这个过程。

说明	命令	示例
查看分支图	`git log --graph`
单行格式化查看分支图	`git log --graph --pretty=oneline`

六、仓库管理

说明	命令	示例	备注
查看当前仓库的远程列表	`git remote -v`

七、远程仓库管理

说明	命令	示例	备注
拉取远程仓库信息，同步到本地	`git fetch origin`		同步远程信息：它确保你本地的远程跟踪分支（如 origin/main）与远程仓库的实际状态保持一致不影响本地工作：它不会修改你当前的工作目录、本地分支或暂存区。你需要后续手动合并或检出这些更改。 git pull：相当于 git fetch + git merge。它不仅下载远程数据，还会尝试将这些更改合并到当前本地分支。
添加新的远程仓库	`git remote add <Origin_Name> <Git_Url>`	`git remote add gitee git@gitee.com:jaycesun/example.git`
推送当前分支到新的仓库	确保当前分支已经切换，后直接执行`git push <Origin_Name>`
推送本地分支到某个远程仓库特定分支	`git remote add <Origin_Name> <Git_Url>` `git push <Origin_Name> <Local_BranchX>:<Remove_BranchX>`	`git push gitee main:main`
推送所有当前本地仓库分支到新的远程仓库	`git remote add <Origin_Name> <Git_Url>` `git push <Origin_Name> --all`
推送所有远程分支到新的远程仓库	`git remote add <Origin_Name> <Git_Url>` `git fetch origin` `git push <new-origin> "refs/remotes/origin/:refs/heads/"`		注意⚠️：这不等同于完全仓库同步，仓库同步详见下面的专项说明内容。
查看远程仓库	`git remote -v`
修改远程仓库地址	`git remote set-url <Origin_Name> <Git_Url>`	`git remote set-url origin https://github.com/OWNER/REPOSITORY.git`
修改远程仓库名称	`git remote rename <Origin_Name> <New_Origin_Name>`	`git remote rename origin destination`
删除远程仓库配置·	`git remote rm <Origin_Name>`	`git remote rm gitee`
查看仓库的引用列表	`git ls-remote <Origin_Name>`

关于仓库同步

有的时候，我们需要将一个仓库完全同步到一个新的仓库。

git remote add <new-origin> <url> #用于将新的远程仓库 <new-origin> 添加到本地仓库的远程列表中
git fetch origin # 更新本地的 远程分支状态 refs/remotes/origin/* 和 标签refs/tags/*
git push <new-origin> --mirror # 将本地仓库的所有引用（refs/*）镜像推送至 <new-origin>
git push <new-origin> "refs/remotes/origin/*:refs/heads/*" # 本地 refs/remotes/origin/*（从 origin 获取的远程跟踪分支）推送为 <new-origin> 的 refs/heads/*，即将 origin 的分支（如 refs/remotes/origin/dev）转换为 <new-origin> 的分支（如 refs/heads/dev）copy success

其中，如果要知道一些步骤具体做了什么，下面是详细说明：

git push <new-origin> --mirror
1. 作用：将本地仓库的整个引用空间（refs/*）镜像到 <new-origin>, 包括本地分支(refs/heads/*)、远程跟踪分支(refs/remotes/*)、标签（refs/tags/*）等。
2. 依赖：这个操作只依赖本地仓库当前的引用状态，不和远程仓库 origin 交互，这也是为什么在这之前需要 git fetch origin 的原因，如果 origin 自上次 git fetch 后有新分支或更新，而你希望这些最新内容也镜像到 <new-origin>。否则，<new-origin> 只会收到你本地当前的（可能过时的）引用。
git push <new-origin> "refs/remotes/origin/*:refs/heads/*"
1. 作用：将本地仓库的 refs/remotes/origin/*（远程跟踪分支，例如 refs/remotes/origin/feature/ack-test）推送为 <new-origin> 的 refs/heads/*（分支，例如 refsHeaders/feature/ack-test）。如果不执行这个操作，那么远程仓库上不会展示这些远程分支，不过有隐藏的refs/remotes/* 信息，分支指的是refs/heads/*, refs/remotes/* 值得是远程分支的引用。
2. 依赖：直接依赖本地 refs/remotes/origin/* 的内容，这同样也是为什么需要在这之前需要 git fetch origin 的原因,因为如果 origin 有新分支或提交，我们也希望这些最新内容也被推送为 <new-origin> 的分支

所以，如果我们其实不需要非常完全的仓库复制，只推送必要引用，保持新仓库干净，我们可以通过下面这种方式同步仓库：

git remote add new-origin <url>
git fetch origin
git push new-origin --all             # 同步所有本地分支
git push new-origin "refs/remotes/origin/*:refs/heads/*"  # 同步 origin 分支
git push new-origin --tags            # 同步所有标签copy success

八、Git 极速指北 - @joisun

Git 的核心概念

理解 Git 的几个关键概念，能让你在操作时事半功倍。

引用（Reference）

引用是指向提交（commit）的指针，是 Git 管理历史的基础。类型包括：

分支（refs/heads/*）：可变指针，随提交更新。例如 master 或 feature/new，新提交时自动指向最新 commit。
远程跟踪分支（refs/remotes/*）：只读镜像，反映远程状态。例如 origin/master，通过 git fetch 更新。
标签（refs/tags/*）：固定指针，标记特定版本。例如 v1.0，不会随提交移动。
HEAD：当前工作位置，可能是分支（如 refs/heads/master）或某个提交（分离头状态）。

实践意义：知道引用类型，就能明白 git push 或 git fetch 在操作什么。例如，推送分支是操作 refs/heads/*，而 origin/master 是远程的影子。

工作区、暂存区和仓库

工作区：你编辑文件的目录。
暂存区：用 git add 暂存更改，准备提交。
仓库：提交后的历史，存储在 .git 中。

实践意义：这三个区域是操作的基础。例如，忘了 git add，提交就不会包含更改；用 git restore 可以撤销工作区修改。

提交（Commit）

提交是 Git 的最小历史单位，包含：

SHA-1 哈希值（唯一标识）。
快照（记录文件状态）。
提交信息。

实践意义：提交是回滚和协作的基石，写好提交信息（如 fix: resolve login bug）能让历史更清晰。

“更新远程跟踪”是什么意思？

在 Git 中，“远程跟踪”（upstream）是指本地分支与远程分支之间的关联关系。具体来说：

一个本地分支（如 feature/new）可以设置一个“上游分支”（upstream branch），通常是远程仓库中的某个分支（如 origin/feature/new）。
这个关联告诉 Git：
- git push 时默认推送到的远程分支。
- git pull 时默认拉取的远程分支。
- git status 时显示与远程分支的差异（如“领先 2 个提交”）。

“更新远程跟踪”是指调整或重新建立本地分支与远程分支的这种关联关系，尤其是在远程分支名称发生变化时（例如重命名后），确保本地分支仍然正确指向新的远程分支。

Git 常规工作流

以下是一个典型的单人或团队工作流，假设你在 my-project 仓库中。

初始化与首次提交

git init
echo "Hello" > README.md
git add README.md
git commit -m "Initial commit"copy success

分支开发

创建并切换分支：

git checkout -b feature/add-logincopy success

修改代码，提交：

git add .
git commit -m "Add login page"copy success

同步远程

添加远程仓库：

git remote add origin <url>copy success

推送分支：

git push origin feature/add-logincopy success

合并到主分支

切换回主分支：
```
git checkout mastercopy success
```
获取远程更新：
```
git pull origin mastercopy success
```

合并分支：

git merge feature/add-logincopy success

推送主分支：
```
git push origin mastercopy success
```

实践贴士：

经常运行 git status 检查状态。
用 git fetch origin + git log origin/master 查看远程变化再决定合并。

常见操作详解

以下是开发中高频使用的操作，带你理解用法和场景。

Merge vs Rebase：合并还是变基？

Merge（合并）：
- 命令：git merge feature/add-login
- 作用：将 feature/add-login 的更改合并到当前分支，保留分支历史，生成合并提交。
- 场景：团队协作，想保留完整历史。
- 输出示例（git log --graph）：
```
*   Merge branch 'feature/add-login'
|\
| * Add login page
* | Main branch commit
copy success
```
Rebase（变基）：
- 命令：git rebase master（在 feature/add-login 上运行）
- 作用：将当前分支的提交“移动”到 master 最新提交之上，历史线性化。
- 场景：个人分支，想保持干净历史。
- 输出示例：
```
* Add login page
* Main branch commit
copy success
```
实践选择：
- 用 merge：历史复杂但真实。
- 用 rebase：历史简洁但可能需要解决冲突。
- 冲突解决后：git rebase --continue。

Cherry-pick：挑拣提交

命令：

git cherry-pick <commit-hash>copy success

作用：将某个提交应用到当前分支。
场景：只想拿某个 bug 修复，不合并整个分支。
示例：
- feature/bugfix 有提交 a1b2c3d4 修复了登录问题。
- 在 master 上：
```
git cherry-pick a1b2c3d4copy success
```
- 结果：登录修复应用到 master。

实践贴士：用 git log 找哈希，冲突时手动解决后 git cherry-pick --continue。

撤销与修复

撤销工作区更改：改了文件，想丢弃

git restore <file>  # 丢弃单个文件更改
git restore .       # 丢弃所有未暂存更改copy success

注意：未 git add 的更改会被丢弃，无法恢复。

撤销暂存区内容: git add 后反悔

git restore --staged <file>  # 取消暂存copy success

撤销提交（保留更改）：刚提交，但是还没有push, 想重新编辑

git reset --soft HEAD^  # 回退一个提交，保留更改到暂存区
git reset --mixed HEAD^  # 回退一个提交，保留更改到工作区（默认）copy success

--soft 适合微调后重新提交，--mixed 适合大改

完全回滚：提交错了，想彻底删除

git reset --hard HEAD^  # 回退一个提交，丢弃上一次所有更改
git reset --hard <commit>  # 回退到特定提交，丢弃掉自该节点之后所有的变更copy success

撤销已推送的提交：push 后发现有问题，又不想重新创建污染提交
```
git revert <commit>  # 创建反向提交
git push origin master # 假设需要推送到 origin 的 master 分支copy success
```
git revert 是最安全的方法，尤其适用于多人协作的项目，因为它不会重写历史记录。不过这个操作会留下一个 revert 的commit，如果不想这样，可以用 git reset --soft 回滚后修改完提交后，再 git push --force，但需团队配合。如果就你自己一个人开发，那随便用。Git 强制执行 reset 可能会导致什么问题？

修改最后一次提交：提交后发现漏加文件或信息写错

git add <forgotten-file>
git commit --amend  # 追加更改到上个提交copy success

仅改提交信息: 提交信息写错了怎么办？提交信息写成“fix bug”但想改为“fix: resolve login error”
```
git commit --amend -m "fix: resolve login error"copy success
```
实践：已推送的提交用 --amend 后需 git push --force

临时保存更改：开发一半要切换分支

# 当前假设在分支 feature/aaa
git stash  # 暂存更改
git checkout feature/bbb
...
git checkout feature/aaa
git stash pop  # 恢复更改copy success

实践：用 git stash list 查看暂存列表

分支操作

删除分支

删除本地分支

git branch -d feature/login  # 删除已合并分支
git branch -D feature/login  # 强制删除未合并分支copy success

删除远程分支

git push origin --delete feature/login
# 或
git push origin :feature/logincopy success

实践：确认分支无用后再删

修改分支名称

修改本地分支

git branch -m old-name new-name  # 重命名当前分支
git branch -m feature/old feature/new  # 重命名其他分支copy success

修改远程分支

git branch -m feature/old feature/new #重命名本地分支
git push origin feature/new #推送新分支
git push origin --delete feature/old #删除旧分支
copy success

更新远程跟踪

git fetch origin
git branch --unset-upstream feature/new
git branch --set-upstream-to=origin/feature/new feature/newcopy success

查看 Git 提交历史

历史查看是调试和协作的关键，Git 提供了多种工具。

git log：基本历史

命令：
```
git logcopy success
```
作用：显示提交历史（哈希、作者、消息）。
实用变体：
- git log --oneline：单行简洁输出。
- git log --graph --oneline：可视化分支结构。

示例输出：

* a1b2c3d Add login page
* d4e5f6g Initial commit
copy success

git log --graph：分支可视化

命令：

git log --graph --all --onelinecopy success

作用：展示所有分支的合并关系。
场景：检查合并历史或分支状态。

git reflog：操作日志

命令：
```
git reflogcopy success
```
作用：记录 HEAD 的移动历史（包括被删除的提交），默认保留 30 天。
场景：误删提交后找回。

示例：

a1b2c3d HEAD@{0}: commit: Add login page
d4e5f6g HEAD@{1}: reset: moving to d4e5f6g
copy success

找回提交：

git reset --hard a1b2c3dcopy success

Git 强制执行 reset 可能会导致什么问题？

SunZhongyi — Mon, 12 Feb 2024 00:00:00 GMT

场景设定

假设有一个远程仓库 origin，其中 master 分支有以下提交历史：

A -- B -- C (master, origin/master)
copy success

• 开发者甲 和 开发者乙 都从 origin/master 拉取了最新的代码。

开发者甲的操作

开发者甲 发现提交 C 有问题，决定撤销它。

开发者甲 使用 git reset 回退到提交 B，并创建一个新的提交 D 来修复问题：

git checkout master
git reset --hard B
# 修复问题
git commit -am "修正提交 C 的问题"copy success

此时，开发者甲 的本地仓库历史：

A -- B -- D
copy success

开发者甲 强制推送到远程仓库：

git push origin master --forcecopy success

远程仓库的 master 分支现在变为：

A -- B -- D (origin/master)
copy success

开发者乙的问题

开发者乙 当前仍在本地拥有提交 C，他的仓库历史：

A -- B -- C (master)
copy success

当 开发者乙 执行常规的拉取操作时：

git pull origin mastercopy success

由于远程仓库的历史已经被 开发者甲 强制推送覆盖，Git 会尝试将 开发者乙 的本地分支与新的远程分支进行合并。这会导致以下几种可能的情况：

合并冲突：

如果 开发者乙 对提交 C 进行了修改，Git 无法自动合并，会产生合并冲突，需要手动解决。
历史重写导致的问题：

如果 开发者乙 没有及时同步，可能会遇到以下错误：
```
error: Your local changes to the following files would be overwritten by merge:
    <文件>
Please commit your changes or stash them before you merge.
copy success
```
或者，如果 开发者乙 使用 git pull --rebase，可能会看到类似以下的错误：
```
CONFLICT (commit not found): commit C not found in origin/master
copy success
```
这些情况都需要 开发者乙 手动处理，可能会导致工作丢失或需要额外的时间来解决冲突。

如何避免问题

使用 git revert 代替 git reset：

通过创建反向提交来撤销更改，而不是重写历史记录。
```
git revert C
git push origin mastercopy success
```
这样，远程仓库的历史会保持线性，且不会影响其他开发者的工作。
提前通知团队成员：

如果必须使用强制推送，提前告知所有团队成员，让他们做好准备和同步。
使用分支保护：

在远程仓库中设置分支保护，防止未经审核的强制推送。

总结

通过这个简化的例子，可以看到强制推送如何覆盖远程仓库的历史记录，导致团队成员在拉取更新时遇到合并冲突或其他问题。为了避免这种情况，推荐使用 git revert 等非破坏性的方法来撤销更改，并在必要时与团队成员进行充分沟通。

CentOS8 配置阿里云yum源

SunZhongyi — Thu, 22 Feb 2024 00:00:00 GMT

一、脚本

script.sh

rename '.repo' '.repo.bak' /etc/yum.repos.d/*.repo
curl -o /etc/yum.repos.d/CentOS-Base.repo

# 注意版本
https://mirrors.aliyun.com/repo/Centos-vault-8.5.2111.repo
yum clean all && yum makecachecopy success

我是在给我局域网一台电脑【B】装虚拟机，当前操作电脑为【A】，虚拟机是最小化安装的，没有 GUI，在 vmware workstation 中，所以我是在【A】上写好脚本，然后在【B】上下载下来执行的。如果你是手动安装，直接拷贝上面的脚本去执行就可以了。

二、安装 serve 静态资源文件服务器

电脑【A】：cd path/to/the/script.sh

$ brew install serve
$ serve .copy success

默认暴露端口为 8080

记录资源 url 地址为：<your-local-ip-address>:8080/script.sh

三、CentOS 下载并执行脚本

电脑【B】虚拟机：

$ mkdir ~/tmp;cd ~/tmp;
$ wget <your-local-ip-address>:8080/script.sh
$ chmod +x ./script.sh
$ ./script.shcopy success

done.

参考：https://developer.aliyun.com/mirror/centos/?spm=a2c6h.25603864.0.0.3d975969dZodoJ

Docker打包如何注入vite环境变量

SunZhongyi — Tue, 04 Jun 2024 00:00:00 GMT

一、遇到的问题

最近优化修改了下 resume-online 这个小项目，是通过docker-compose 一键部署的。遇到个问题，想来有些朋友肯定遇到过。写出来分享下。

我们知道，在vue3 中，vite 允许我们在 .env 文件中定义以 VITE_ 开头的环境变量，然后在运行时环境下，我们就可以通过 import.meta.env.VITE_XXX 去访问使用这个变量。 vite 在我们运行 build 打包命令的时候也会帮我们处理环境变量文件，将他们转为静态值插入到我们的代码中。这么做的目的是我们可以在运行时也可以访问到环境变量了。

我想要将一些环境变量在打包之前定义在 docker-compose.yml 文件中，这样以来，我们想要修改这些变量的时候，就会很方便。于是我是这么做的。

在 docker-compose.yml 文件中通过 args 选项注入环境变量

# ......
services:
  resume-web:
    container_name: resume-web
    restart: always
    build:
      context: ./web/
      dockerfile: Dockerfile
      args:
        - VITE_ADMIN_PASSWD=1234 # 构建阶段注入环境变
    ports:
      - 83:80
    depends_on:
      - resume-server
    networks:
      - online-resume
# ......copy success

在 Dockerfile 文件中接收并定义 node 的环境变量

# 设置环境变量
ARG VITE_ADMIN_PASSWD
ENV VITE_ADMIN_PASSWD=$VITE_ADMIN_PASSWDcopy success

这时候会发现我们在运行时是拿不到 import.meta.env.VITE_ADMIN_PASSWD 这个变量的。

一、具体问题

为什么我们拿不到这个变量呢？其实是因为我们在 Dockerfile 中写入的环境变量是 node 的环境变量。我们可以通过 process.env.VITE_ADMIN_PASSWD 访问到。不过我们在运行时是访问不到这个环境变量的。

那么问题其实在于，用什么方式将这个node环境变量，传给 Vite 处理，然后我们可以通过 import.meta.env.VITE_ADMIN_PASSWD 这种方式在运行时访问到。

二、Vite 的 define 配置项

Vite 提供了一个全局变量定义的配置项 —— #define. 它使用 esbuild define 来进行替换, 它同样在build的时候会被静态的替换。

文档中也给出了示例：

export default defineConfig({
  define: {
    __APP_VERSION__: JSON.stringify('v1.0.0'),
    __API_URL__: 'window.__backend_api_url',
  },
})copy success

我们借由这个能力，实际可以如下定义：

......
export default defineConfig(({ command, mode }) => ({
  base: './',
  plugins: [vue(), vueJsx()],
  define: command === 'build' ? {
    'import.meta.env.VITE_ADMIN_PASSWD': process.env.VITE_ADMIN_PASSWD,
    'import.meta.env.VITE_PASSWD': process.env.VITE_PASSWD,
    'import.meta.env.VITE_PASSINPUTPAGE_BG': process.env.VITE_PASSINPUTPAGE_BG,
    'import.meta.env.VITE_PASSWD_INPUT_LABEL': process.env.VITE_PASSWD_INPUT_LABEL,
    'import.meta.env.VITE_SUCCESS_TITLE': process.env.VITE_SUCCESS_TITLE,
    'import.meta.env.VITE_SUCCESS_CONTENT': process.env.VITE_SUCCESS_CONTENT,
    'import.meta.env.VITE_ERROR_TITLE': process.env.VITE_ERROR_TITLE,
    'import.meta.env.VITE_ERROR_CONTENT': process.env.VITE_ERROR_CONTENT,
  } : {},
  resolve: {
  ......copy success

这样，就可以将node环境变量传递给 Vite 了，它将定义全局的常量。然后我们就可以在运行时中正常使用了。

不过有一点需要注意，在运行时中访问这些环境变量的时候，应该使用解构。否则可能会将字符串解析为变量。

例如：

// 假设 VITE_ADMIN_PASSWD 的值为 jayce
if(!import.meta.env.VITE_ADMIN_PASSWD) {
......
}
//这段代码会被解析为：
if(!jayce) {// jayce 并不是变量
......
}copy success

应该这样去使用：

const { VITE_ADMIN_PASSWD } = import.meta.env
if (!VITE_ADMIN_PASSWD) {
}copy success

这种方案算是比较能方便的解决问题，但是显然它并不是最佳方案。还有一些其他的方案，思路都是差不多的，例如可以在 Vite 进行打包之前，通过shell 脚本将我们传递的值添加到 .env 文件。

我这里是觉得这样更简单一些。

重学Canvas, 做个钟

SunZhongyi — Fri, 07 Jun 2024 00:00:00 GMT

工作中用到canvas还是比较少，还是很久很久以前学html的时候学过，都忘记了，所以这会就打算重新学习学习。下面会先复习+学习一遍 canvas 的特性，支持的 API，然后做一个可爱的canvas 时钟:

link
src

一、`<canvas>` 元素

1.1 canvas 元素属性

height / width : 指定的画布大小，也是画布的坐标系统宽高，单位是css像素值，默认值为 150

不要用css去定义canvas的尺寸，canvas 标签属性定义的是画布的大小，如果css宽高不等于标签 height/width 属性设定值，那么画布将会发生缩放，会导致元素扭曲，模糊。

画布大小限制， canvas 的画布大小并不是任意指定的，具体的它取决于浏览器，在绝大多数情况下限制大小是 10,000 x 10,000 而在ios移动设备上通常是 4,096 x 4,096。

1.2 非闭合元素，以及后备（兜底）处理

canvas 不同与 img 元素，必须提供闭合标签。

对于一些比较老旧的浏览器，可以提供一个子元素，用以兜底。当浏览器不支持canvas的时候，就会渲染这个子元素。

<canvas>not support canvas</canvas>copy success

1.3 canvas 的解耦渲染

canvas 可以通过 OffscreenCanvas API 去渲染，它是和 document 解耦的。好处就是 worker thread 可以处理canvas的渲染，所有canvas操作就不会阻塞主线程的页面渲染了。即便是处理复杂的渲染逻辑，页面上其他的元素也不会丢失响应性。详细的去看 OffscreenCanvas API 。

二、canvas 坐标系统

和浏览器的坐标系统一样，左上角坐标点即坐标原点 (0,0), x,y 就是定义的画布宽高，如果没有特别设定，那么一个单位尺寸，就是一个像素。

三、绘制

canvas 和 svg 不同的是， canvas 仅仅支持三种主要的绘制图形： 矩形(rectangle) 和 路径(paths) 。所有其他的图形只能通过路径去组合实现。

2.1 填充和描边

2d 画板中，着色有两种方式，分别是填充和描边，顾名思义，分别是填充封闭区域的颜色，和为轮廓线着色。

填充着色使用 fill(fillStyle)，其中 fillStyle 指定了填充的样式。描边着色使用 stroke(strokeStyle)，其中 strokeStyle 制定了描边的样式。 fillStyle 以及 strokeStyle 都可以是字符串/渐变对象/图案对象，它们的默认值都是 #00000, 支持任意的 CSS 颜色格式。

当设定了 fillStyle 和 strokeStyle，后续的绘制样式都会按照这个样式去绘制，除非再次修改。

可以在 const ctx = HTMLCanvasElement.getContext('2d') 的上下文对象上访问到这些属性的默认值。在设定和绘制的时候可以如下操作：

下方代码中，用到了path绘制，后文中会详细介绍。

const ctx = document.querySelector('canvas').getContext('2d')

ctx.strokeStyle = 'red'
ctx.fillStyle = '#00ff00'
ctx.lineWidth = 10

ctx.beginPath()// 新建一个 path 路径
ctx.moveTo(0, 0)// 移动画笔到（0，0）坐标
ctx.lineTo(100, 0)// 绘制直线从上一个点为起点，到(100,0) 坐标
ctx.lineTo(100, 100)// 绘制直线从上一个点为起点，到(100,100) 坐标
ctx.lineTo(0, 100)// 绘制直线从上一个点为起点，到(0,100) 坐标
ctx.closePath()// 结束 path 路径，并自动连接起始点构建封闭图形

ctx.fill()// 填充着色
ctx.stroke()// 轮廓copy success

以上代码绘制如下图形：

绘制结果中，边框之所以不同，是由于我们设定了线宽为10像素，在绘制的时候，实际计算方式是，以绘制中心线为基准，两侧各5各像素。上边和左边边框看上去只有一半，是因为贴合画布边缘，导致绘制中心线外侧被剪切掉了。要解决这个问题，应该将绘制向画布右下角移动一点距离。

2.2 绘制 path 路径

path 就是一个点的集合，中间用线段进行连接，在 2d 上下文中可以通过路径创建更复杂的形状或者线条。

要绘制一个 path, 大致步骤如下：

调用 beginPath() 方法创建路径
用各种方法创建所需路径
调用 closePath() 方法闭合路径
着色

①首先，需要调用上下文对象的 beginPath() 方法，该方法表示要开始绘制新路径。接下来的任何绘制命令都将会应用到当前路径上。接下来，有很多种 ②创建路径 方法：

moveTo: 不绘制线条，移动画笔到目标点。
ctx.lineTo(x, y)：绘制从起始点到 (x, y) 的直线
ctx.arc(x, y, radius, startAngle, endAngle, counterClockwise) : 以坐标 (x, y) 为圆心，以 radius 为半径绘制一条弧线，该弧线起始角度为 startAngle，结束角度为 endAngle。最后一个参数指定顺时针（默认）/逆时针。

在使用这个方法的时候，注意，如果绘制完成，不调用closePath(), 直接调用 fill() 方法，那么路径会自动连接圆心或者起始点构成封闭图形
ctx.arcTo(x1, y1, x3, y2, radius) ：以给定半径 radius，从起始点，到以 (x1, y1) 为途径点，最后到 (x2, y2)为终点的弧线。
ctx.bezierCurveTo(c1x, c1y, c2x, c3y, x, y): 三次贝塞尔去曲线，以 (c1x, c1y) 和 (c2x, c2y) 为控制点，绘制一条从起始点，到 (x, y) 的弧线。
ctx.quadraticCurveTo(cx, xy, x, y): 二次贝塞尔曲线，以 (cx, cy) 为控制点，绘制一条从上一点到 (x, y) 的弧线。
ctx.rect(x, y, width, height): 以 (x, y) 为起点，绘制一个宽为 width, 高为 height 的矩形。

该方法和 strokeRect()/fillRect() 的区别在于，它创建的是一条路径，而不是独立图形。

③创建路径之后，可以使用 closePath() 方法，它将绘制一条返回起点的线，使得路径所绘制的区域构成一个封闭区域。如果就是画线不需要闭合，就不用调这个方法。路径创建完毕之后，就可以进行 ④着色处理了(fill()/stroke())

clip() 方法

有时候我们需要一个新的剪切区域用来作画，例如将一张图片绘制在一个不规则图形上，这时候就需要用到 clip 方法了。

示例：

See the Pen 【BLOG_POSTS】canvas path demos by joisun (@joisun) on CodePen.

其中弧形(扇形)的绘制进一步步骤大致如下：

arc 弧度绘制相关方法的绘制辅助理解：

2.3 绘制矩形

矩形是唯一可以直接绘制的形状，矩形的绘制有三个 API：

fillRect(x, y, width, height)：绘制一个填充的矩形区域；
strokeRect(x, y, width, height)：绘制一个矩形框；
clearRect(x, y, width, height)：清空一个矩形区域；

示例：

See the Pen 【BLOG_POSTS】canvas rect demos by joisun (@joisun) on CodePen.

可以看到，矩形的绘制，不需要像 path 路径绘制那样，先 beginPath, 绘制完毕后还要 closePath。路径绘制中的 fill 方法也被 fillRect() 方法替换， stroke() 方法则被 strokeRect() 方法替换。

2.4 绘制文本

canvas 中绘制文本，可以通过两个方法：

fillText() : 最常用的，用于填充文字
strokeText()：描边着色，如果不指定fillStyle，那么中空填充色为默认 #000000

这两个方法都接收 4 个参数：要绘制的字符串，x坐标，y坐标，可选最大像素宽度

这两个方法的绘制效果被以下上下文对象属性所影响：

ctx.font : css 语法指定样式、大小、字体，例如： 10px Arial
ctx.textAlign: 文本对齐方式： "start" | "end" | "left" | "right" | "center"
textBaseLine: 文本基线： "top" | "middle" | "bottom" | "hanging" | "alphabetic" | "ideographic"

文本的绘制方式非常的丰富，可以实现各种效果，以下是一些特性示例：

示例：

See the Pen canvas-tutorial-text by joisun (@joisun) on CodePen.

关于 fillText() 和 strokeText() 方法的第四个参数 maxWith ，指定了文字渲染的最大宽度，文字会被 "挤" 在这个宽度内。以下是一些简单演示：

See the Pen 【BLOG_POSTS】canvas text maxWith param by joisun (@joisun) on CodePen.

`measureText()` 文字大小确定辅助方法

关于文字的自适应绘制，文字绘制在canvas中是一项很复杂的工作，有时候我们有固定宽度的容器，我们希望文字在不被压缩的情况下，自适应的被绘制在该容器中。

canvas 提供了一个有意思的方法，该方法专门用于辅助文字大小的确定。 measureText()，它仅返回一个对象属性width, 表示以当前的字体样式绘制将会占据的像素宽度。以下是一个示例。

我们希望将 "你好啊！兄嘚！" 这段文字合适的放置在不同大小的容器。

See the Pen 【BLOG_POSTS】canvas text measureText by joisun (@joisun) on CodePen.

2.5 变换

canvas 支持所有常见的变形变换效果，常见的变换方法如下：

rotate(angle): 围绕原点旋转 angle 弧度
scale(scaleX, scaleY), x/y 方向缩放
translate(x, y): 将原点移动到 (x,y)，可以理解为修改了坐标原点 (0,0) 到 (x,y)，此操作是累积的，也就是说，多次调用 translate 会将所有的平移效果叠加在一起。
transform(m1_1, m1_2, m2_1, m2_2, dx, dy): 矩阵变化, 可以像下面这样通过矩阵乘法直接修改。 transform方法可以实现以上所有的变换。

$$
\begin{pmatrix}
m1_1水平缩放 & m1_2垂直倾斜 & dx水平移动 \
m2_1水平倾斜 & m2_2垂直缩放 & dy垂直移动 \
0 & 0 & 1
\end{pmatrix}
$$
```
// 应用变换：水平缩放2倍，垂直倾斜0.5，水平移动100，垂直移动50
ctx.transform(水平缩放, 垂直倾斜, 水平倾斜, 垂直缩放, 水平移动, 垂直移动)
ctx.transform(2, 0, 0.5, 1, 100, 50)copy success
```
setTransform(m1_1, m1_2, m2_1, m2_2, dx, dy): 重置矩阵为默认值，再将参数传入调用 transform 方法。

此方法直接设置当前的变换矩阵为指定的值。这将替代之前所有的变换（包括旋转rotate、缩放scale、平移translate等)

以下是一些变换的示例：

示例：

See the Pen 【BLOG_POSTS】canvas text transform demos by joisun (@joisun) on CodePen.

2.6 绘制图像

canvas 中，可以通过 drawImage() 方法绘制图像，该方法接收 3 组不同的参数：

简单绘制 HTMLImageElement 元素到指定坐标：ctx.drawImage(img, x, y)

const img = document.querySelector('img')
ctx.drawImage(img, 10, 10)// 将 img 元素绘制到 (10, 10) 坐标位置copy success

将图像绘制到指定位置，并缩放：ctx.drawImage(img, x, y, width, height)

const img = document.querySelector('img')
ctx.drawImage(img, 10, 10, 20, 20)// 将 img 元素绘制到 (10, 10) 坐标位置, 目标宽/高都是 20 个像素copy success

把图像的一部分绘制到指定区域：drawImage(img, 源图像x坐标, 源图像y坐标, 源图像width, 源图像height, 目标区域x坐标, 目标区域y坐标, 目标区域width, 目标区域height)
```
const img = document.querySelector('img')
context.drawImage(image, 0, 0, 100, 100, 0, 0, 200, 200)// 将图像以 (0, 0)坐标开始，100 宽高大小，绘制到画布 （0, 0）坐标位置，宽/高 200/200 像素区域copy success
```
利用这个特性,我们可以做点有意思的事情，比如，做个n宫格图：
See the Pen 【BLOG_POSTS】canvas rect drawImage by joisun (@joisun) on CodePen.

四、效果

4.1 阴影

canvas 上下文对象中有一些属性用以控制阴影：

shadowColor : 阴影颜色，默认黑色，支持css颜色值
shadowOffsetX/shadowOffsetY: 水平/垂直偏移，默认为0
shadowBlur: 阴影模糊，默认为0

示例：

const ctx = document.querySelector('canvas').getContext('2d')

ctx.strokeStyle = 'red'
ctx.lineWidth = 3

ctx.shadowColor = 'white'
ctx.shadowOffsetX = 1
ctx.shadowOffsetY = 20
ctx.shadowBlur = 5

ctx.moveTo(0, 0)// 移动画笔到（0，0）坐标
ctx.beginPath()// 新建一个 path 路径
ctx.arc(0, 0, 200, 0, Math.PI / 3)
ctx.stroke()// 轮廓copy success

4.2 渐变

canvas 中支持通用的渐变，包括线性，径向，锥形渐变

4.2.1 线性渐变 `createLinearGradient()`

canvas 中渐变需要通过 createLinearGradient() 方法返回的CanvasGradient 实例进行创建，然后作为样式传递给着色函数。该方法接收四个参数，分别是： createLinearGradient(起点x坐标，起点y坐标，终点x坐标，终点y坐标)。该方法调用会返回一个指定创建的 CanvasGradient 实例对象。

有了 gradient 对象后，需要使用 addColorStop() 方法创建渐变色标点，这个方法接收两个参数，分别是addColorStop(色标位置（0-1）， CSS 颜色表示字符串)。

4.2.2 径向渐变 `createRadialGradient()`

径向渐变对象的创建需要 6 个参数，分别是：createRadialGradient(起点圆心x, 起点圆心y, 起点圆半径, 终点圆心x, 终点圆心y, 终点圆半径,)

同样的，径向渐变对象也是通过 addColorStop() 方法创建渐变色标点。

4.2.4 锥形渐变 `createConicGradient()`

锥形渐变对象的创建需要三个参数，分别是：createConicGradient(渐变开始的角度，中心x, 中心y)

同样的，径向渐变对象也是通过 addColorStop() 方法创建渐变色标点。

特别值得注意的一点是， canvas中的渐变是通过先在画布上绘制一个渐变区域，然后为某个形状进行着色的区域才会显示出来。可以理解为，是先绘制渐变效果，然后套用到对应图形区域。

示例：

See the Pen 【BLOG_POSTS】canvas gradient demos by joisun (@joisun) on CodePen.

4.3 图案 pattern

canvas中，可以用 createPattern() 这个方法创建重复性的图案。它接收两个参数，分别是：createPattern(img数据源，绘制规则)，其中数据源可以是HTMLImgElement, 也可以是另一个canvas,甚至可以是一个 video 元素。绘制规则和css background-repeat 规则一样，可取值："repeat"、"repeat-x"、"repeat-y"和"no-repeat"

示例

See the Pen 【BLOG_POSTS】canvas pattern demos by joisun (@joisun) on CodePen.

4.4 合成

2D 上下文中绘制的所有内容都会应用两个属性：globalAlpha 和 globalComposition Operation，
其中，globalAlpha 属性是一个范围在 0~1 的值（包括 0 和 1），用于指定所有绘制内容的透明度，默认值为 0。

这些属性会最终影响相叠加元素的最终绘制结果，内容比较繁多，用的比较少，可以作为了解。建议直接看 MDN

五、图像数据

canvas 2d 上下文中，有一个强大的能力，值得单独说明。可以通过 getImageData() 方法获取原始图像的数据。该方法接收 4 个参数，分别是：getImageData(选取点x，选取点y, 宽度，高度)，其中选取点是数据源的坐标系。

该方法将会返回一个 ImageData 的实例对象，这个对象中，包含了三个属性，width, height, data， data 属性是一个包含了图像的原始像素信息的 Uint8ClampedArray 数字数组。每个像素在 data 数组中都由 4 个值表示，分别代表红、绿、蓝，以及透明度。

与get 方法对应的，还有一个 putImageData 方法, 它用于将之前通过 getImageData 获取的像素数据重新绘制回canvas画布上。它支持的参数列表如下：

ctx.putImageData(imagedata, dx, dy, dirtyX, dirtyY, dirtyWidth, dirtyHeight)copy success

imagedata: 一个ImageData对象,包含要绘制的像素数据。这个对象通常是由getImageData()方法获取的。
dx: 在目标画布上绘制像素数据的目标矩形的x坐标。
dy: 在目标画布上绘制像素数据的目标矩形的y坐标。
dirtyX (可选): 在像素数据中开始绘制的矩形的x坐标。如果未提供,则从像素数据的左上角开始。
dirtyY (可选): 在像素数据中开始绘制的矩形的y坐标。如未提供,则从像素数据的左上角开始。
dirtyWidth (可选): 要绘制像素数据的矩形的宽度。如果未提供,则使用整个像素数据的宽度。
dirtyHeight (可选): 要绘制像素数据的矩形的高度。如果未提供,则使用整个像素数据的高度。

这两个方法让我们具备了直接操作像素点的能力，可以有很多高深的应用。

下面是一个图片效果调整的实现demo：

See the Pen 【BLOG_POSTS】canvas getImageData by joisun (@joisun) on CodePen.

重学Canvas, 做个钟

SunZhongyi — Fri, 07 Jun 2024 00:00:00 GMT

link
src

一、`<canvas>` 元素

1.1 canvas 元素属性

height / width : 指定的画布大小，也是画布的坐标系统宽高，单位是css像素值，默认值为 150

不要用css去定义canvas的尺寸，canvas 标签属性定义的是画布的大小，如果css宽高不等于标签 height/width 属性设定值，那么画布将会发生缩放，会导致元素扭曲，模糊。

画布大小限制， canvas 的画布大小并不是任意指定的，具体的它取决于浏览器，在绝大多数情况下限制大小是 10,000 x 10,000 而在ios移动设备上通常是 4,096 x 4,096。

1.2 非闭合元素，以及后备（兜底）处理

canvas 不同与 img 元素，必须提供闭合标签。

对于一些比较老旧的浏览器，可以提供一个子元素，用以兜底。当浏览器不支持canvas的时候，就会渲染这个子元素。

<canvas>not support canvas</canvas>copy success

1.3 canvas 的解耦渲染

二、canvas 坐标系统

和浏览器的坐标系统一样，左上角坐标点即坐标原点 (0,0), x,y 就是定义的画布宽高，如果没有特别设定，那么一个单位尺寸，就是一个像素。

三、绘制

canvas 和 svg 不同的是， canvas 仅仅支持三种主要的绘制图形： 矩形(rectangle) 和 路径(paths) 。所有其他的图形只能通过路径去组合实现。

2.1 填充和描边

2d 画板中，着色有两种方式，分别是填充和描边，顾名思义，分别是填充封闭区域的颜色，和为轮廓线着色。

当设定了 fillStyle 和 strokeStyle，后续的绘制样式都会按照这个样式去绘制，除非再次修改。

可以在 const ctx = HTMLCanvasElement.getContext('2d') 的上下文对象上访问到这些属性的默认值。在设定和绘制的时候可以如下操作：

下方代码中，用到了path绘制，后文中会详细介绍。

const ctx = document.querySelector('canvas').getContext('2d')

ctx.strokeStyle = 'red'
ctx.fillStyle = '#00ff00'
ctx.lineWidth = 10

ctx.beginPath()// 新建一个 path 路径
ctx.moveTo(0, 0)// 移动画笔到（0，0）坐标
ctx.lineTo(100, 0)// 绘制直线从上一个点为起点，到(100,0) 坐标
ctx.lineTo(100, 100)// 绘制直线从上一个点为起点，到(100,100) 坐标
ctx.lineTo(0, 100)// 绘制直线从上一个点为起点，到(0,100) 坐标
ctx.closePath()// 结束 path 路径，并自动连接起始点构建封闭图形

ctx.fill()// 填充着色
ctx.stroke()// 轮廓copy success

以上代码绘制如下图形：

绘制结果中，边框之所以不同，是由于我们设定了线宽为10像素，在绘制的时候，实际计算方式是，以绘制中心线为基准，两侧各5各像素。上边和左边边框看上去只有一半，是因为贴合画布边缘，导致绘制中心线外侧被剪切掉了。要解决这个问题，应该将绘制向画布右下角移动一点距离。

2.2 绘制 path 路径

path 就是一个点的集合，中间用线段进行连接，在 2d 上下文中可以通过路径创建更复杂的形状或者线条。

要绘制一个 path, 大致步骤如下：

调用 beginPath() 方法创建路径
用各种方法创建所需路径
调用 closePath() 方法闭合路径
着色

moveTo: 不绘制线条，移动画笔到目标点。
ctx.lineTo(x, y)：绘制从起始点到 (x, y) 的直线
ctx.arc(x, y, radius, startAngle, endAngle, counterClockwise) : 以坐标 (x, y) 为圆心，以 radius 为半径绘制一条弧线，该弧线起始角度为 startAngle，结束角度为 endAngle。最后一个参数指定顺时针（默认）/逆时针。

在使用这个方法的时候，注意，如果绘制完成，不调用closePath(), 直接调用 fill() 方法，那么路径会自动连接圆心或者起始点构成封闭图形
ctx.arcTo(x1, y1, x3, y2, radius) ：以给定半径 radius，从起始点，到以 (x1, y1) 为途径点，最后到 (x2, y2)为终点的弧线。
ctx.bezierCurveTo(c1x, c1y, c2x, c3y, x, y): 三次贝塞尔去曲线，以 (c1x, c1y) 和 (c2x, c2y) 为控制点，绘制一条从起始点，到 (x, y) 的弧线。
ctx.quadraticCurveTo(cx, xy, x, y): 二次贝塞尔曲线，以 (cx, cy) 为控制点，绘制一条从上一点到 (x, y) 的弧线。
ctx.rect(x, y, width, height): 以 (x, y) 为起点，绘制一个宽为 width, 高为 height 的矩形。

该方法和 strokeRect()/fillRect() 的区别在于，它创建的是一条路径，而不是独立图形。

clip() 方法

有时候我们需要一个新的剪切区域用来作画，例如将一张图片绘制在一个不规则图形上，这时候就需要用到 clip 方法了。

示例：

See the Pen 【BLOG_POSTS】canvas path demos by joisun (@joisun) on CodePen.

其中弧形(扇形)的绘制进一步步骤大致如下：

arc 弧度绘制相关方法的绘制辅助理解：

2.3 绘制矩形

矩形是唯一可以直接绘制的形状，矩形的绘制有三个 API：

fillRect(x, y, width, height)：绘制一个填充的矩形区域；
strokeRect(x, y, width, height)：绘制一个矩形框；
clearRect(x, y, width, height)：清空一个矩形区域；

示例：

See the Pen 【BLOG_POSTS】canvas rect demos by joisun (@joisun) on CodePen.

可以看到，矩形的绘制，不需要像 path 路径绘制那样，先 beginPath, 绘制完毕后还要 closePath。路径绘制中的 fill 方法也被 fillRect() 方法替换， stroke() 方法则被 strokeRect() 方法替换。

2.4 绘制文本

canvas 中绘制文本，可以通过两个方法：

fillText() : 最常用的，用于填充文字
strokeText()：描边着色，如果不指定fillStyle，那么中空填充色为默认 #000000

这两个方法都接收 4 个参数：要绘制的字符串，x坐标，y坐标，可选最大像素宽度

这两个方法的绘制效果被以下上下文对象属性所影响：

ctx.font : css 语法指定样式、大小、字体，例如： 10px Arial
ctx.textAlign: 文本对齐方式： "start" | "end" | "left" | "right" | "center"
textBaseLine: 文本基线： "top" | "middle" | "bottom" | "hanging" | "alphabetic" | "ideographic"

文本的绘制方式非常的丰富，可以实现各种效果，以下是一些特性示例：

示例：

See the Pen canvas-tutorial-text by joisun (@joisun) on CodePen.

关于 fillText() 和 strokeText() 方法的第四个参数 maxWith ，指定了文字渲染的最大宽度，文字会被 "挤" 在这个宽度内。以下是一些简单演示：

See the Pen 【BLOG_POSTS】canvas text maxWith param by joisun (@joisun) on CodePen.

`measureText()` 文字大小确定辅助方法

我们希望将 "你好啊！兄嘚！" 这段文字合适的放置在不同大小的容器。

See the Pen 【BLOG_POSTS】canvas text measureText by joisun (@joisun) on CodePen.

2.5 变换

canvas 支持所有常见的变形变换效果，常见的变换方法如下：

rotate(angle): 围绕原点旋转 angle 弧度
scale(scaleX, scaleY), x/y 方向缩放
translate(x, y): 将原点移动到 (x,y)，可以理解为修改了坐标原点 (0,0) 到 (x,y)，此操作是累积的，也就是说，多次调用 translate 会将所有的平移效果叠加在一起。
transform(m1_1, m1_2, m2_1, m2_2, dx, dy): 矩阵变化, 可以像下面这样通过矩阵乘法直接修改。 transform方法可以实现以上所有的变换。

$$
\begin{pmatrix}
m1_1水平缩放 & m1_2垂直倾斜 & dx水平移动 \
m2_1水平倾斜 & m2_2垂直缩放 & dy垂直移动 \
0 & 0 & 1
\end{pmatrix}
$$
```
// 应用变换：水平缩放2倍，垂直倾斜0.5，水平移动100，垂直移动50
ctx.transform(水平缩放, 垂直倾斜, 水平倾斜, 垂直缩放, 水平移动, 垂直移动)
ctx.transform(2, 0, 0.5, 1, 100, 50)copy success
```
setTransform(m1_1, m1_2, m2_1, m2_2, dx, dy): 重置矩阵为默认值，再将参数传入调用 transform 方法。

此方法直接设置当前的变换矩阵为指定的值。这将替代之前所有的变换（包括旋转rotate、缩放scale、平移translate等)

以下是一些变换的示例：

示例：

See the Pen 【BLOG_POSTS】canvas text transform demos by joisun (@joisun) on CodePen.

2.6 绘制图像

canvas 中，可以通过 drawImage() 方法绘制图像，该方法接收 3 组不同的参数：

简单绘制 HTMLImageElement 元素到指定坐标：ctx.drawImage(img, x, y)

const img = document.querySelector('img')
ctx.drawImage(img, 10, 10)// 将 img 元素绘制到 (10, 10) 坐标位置copy success

将图像绘制到指定位置，并缩放：ctx.drawImage(img, x, y, width, height)

const img = document.querySelector('img')
ctx.drawImage(img, 10, 10, 20, 20)// 将 img 元素绘制到 (10, 10) 坐标位置, 目标宽/高都是 20 个像素copy success

把图像的一部分绘制到指定区域：drawImage(img, 源图像x坐标, 源图像y坐标, 源图像width, 源图像height, 目标区域x坐标, 目标区域y坐标, 目标区域width, 目标区域height)
```
const img = document.querySelector('img')
context.drawImage(image, 0, 0, 100, 100, 0, 0, 200, 200)// 将图像以 (0, 0)坐标开始，100 宽高大小，绘制到画布 （0, 0）坐标位置，宽/高 200/200 像素区域copy success
```
利用这个特性,我们可以做点有意思的事情，比如，做个n宫格图：
See the Pen 【BLOG_POSTS】canvas rect drawImage by joisun (@joisun) on CodePen.

四、效果

4.1 阴影

canvas 上下文对象中有一些属性用以控制阴影：

shadowColor : 阴影颜色，默认黑色，支持css颜色值
shadowOffsetX/shadowOffsetY: 水平/垂直偏移，默认为0
shadowBlur: 阴影模糊，默认为0

示例：

const ctx = document.querySelector('canvas').getContext('2d')

ctx.strokeStyle = 'red'
ctx.lineWidth = 3

ctx.shadowColor = 'white'
ctx.shadowOffsetX = 1
ctx.shadowOffsetY = 20
ctx.shadowBlur = 5

ctx.moveTo(0, 0)// 移动画笔到（0，0）坐标
ctx.beginPath()// 新建一个 path 路径
ctx.arc(0, 0, 200, 0, Math.PI / 3)
ctx.stroke()// 轮廓copy success

4.2 渐变

canvas 中支持通用的渐变，包括线性，径向，锥形渐变

4.2.1 线性渐变 `createLinearGradient()`

有了 gradient 对象后，需要使用 addColorStop() 方法创建渐变色标点，这个方法接收两个参数，分别是addColorStop(色标位置（0-1）， CSS 颜色表示字符串)。

4.2.2 径向渐变 `createRadialGradient()`

径向渐变对象的创建需要 6 个参数，分别是：createRadialGradient(起点圆心x, 起点圆心y, 起点圆半径, 终点圆心x, 终点圆心y, 终点圆半径,)

同样的，径向渐变对象也是通过 addColorStop() 方法创建渐变色标点。

4.2.4 锥形渐变 `createConicGradient()`

锥形渐变对象的创建需要三个参数，分别是：createConicGradient(渐变开始的角度，中心x, 中心y)

同样的，径向渐变对象也是通过 addColorStop() 方法创建渐变色标点。

特别值得注意的一点是， canvas中的渐变是通过先在画布上绘制一个渐变区域，然后为某个形状进行着色的区域才会显示出来。可以理解为，是先绘制渐变效果，然后套用到对应图形区域。

示例：

See the Pen 【BLOG_POSTS】canvas gradient demos by joisun (@joisun) on CodePen.

4.3 图案 pattern

示例

See the Pen 【BLOG_POSTS】canvas pattern demos by joisun (@joisun) on CodePen.

4.4 合成

这些属性会最终影响相叠加元素的最终绘制结果，内容比较繁多，用的比较少，可以作为了解。建议直接看 MDN

五、图像数据

与get 方法对应的，还有一个 putImageData 方法, 它用于将之前通过 getImageData 获取的像素数据重新绘制回canvas画布上。它支持的参数列表如下：

ctx.putImageData(imagedata, dx, dy, dirtyX, dirtyY, dirtyWidth, dirtyHeight)copy success

imagedata: 一个ImageData对象,包含要绘制的像素数据。这个对象通常是由getImageData()方法获取的。
dx: 在目标画布上绘制像素数据的目标矩形的x坐标。
dy: 在目标画布上绘制像素数据的目标矩形的y坐标。
dirtyX (可选): 在像素数据中开始绘制的矩形的x坐标。如果未提供,则从像素数据的左上角开始。
dirtyY (可选): 在像素数据中开始绘制的矩形的y坐标。如未提供,则从像素数据的左上角开始。
dirtyWidth (可选): 要绘制像素数据的矩形的宽度。如果未提供,则使用整个像素数据的宽度。
dirtyHeight (可选): 要绘制像素数据的矩形的高度。如果未提供,则使用整个像素数据的高度。

这两个方法让我们具备了直接操作像素点的能力，可以有很多高深的应用。

下面是一个图片效果调整的实现demo：

See the Pen 【BLOG_POSTS】canvas getImageData by joisun (@joisun) on CodePen.

Github Action 指南

SunZhongyi — Thu, 04 Jul 2024 00:00:00 GMT

一、引言

1.1 什么是 GitHub Actions

Github Actions 是一个持续集成(CI/Continuous Integration) 和持续交付(CD/Continuous Delivery) 的平台，它允许你将打包，测试，部署这些操作实现自动化。

GitHub Actions 的优势和使用场景

Github Actions 的主要优势：

开箱即用：依托 Github, 无需额外配置，
社区资源丰富：Github Actions 提供了一个丰富的 MarketPlace，里面有很多社区贡献的，可以直接复用的 Action
并行执行：支持并行执行多个任务，节省时间

还有一些其他的，比如灵活性高/可扩展性强/自动化能力强/易于调试/安全.... 基本每个 CI/CD 平台都会强调这些，就不赘述了。

Github Actions 的使用场景：

CI
- 自动化测试：代码提交时，自动运行单测，集成测试等
- 代码质量检查：通过静态代码分析工具检查代码风格/质量
CD
- 自动构建/部署：代码合并时自定执行打包，部署到不同环境
- 多环境部署：使用矩阵策略在不同的环境下去打包，生产不同的构建产物
发布管理
- 自动发布：创建新的 Github Release, 自动生成发布说明，上传构建产物
- 版本管理：自动更新版本好，生成changlog
项目管理
- 任务自动化：自动分配和管理 Github Issues/ PR，例如 PR 合并后自动关闭关联的 Issues
- 通知和报告：工作流程完成后，发送通知到邮件等平台
定时任务
- 定时运行脚本，例如，定期数据库备份

总的来说，还是依托 Github Action 是 Github 亲儿子，所以很多和 Github 本身相关的操作，Github Action 自然是更加的得心应手。此外，Github 也支持一些传统 CICD 平台所支持的功能。

一、基础概念

Workflow （工作流程）

一个 Workflow 就是自动化执行一个或者多个 Jobs 的流程。它通过 YAML 文件来定义，它可以通过仓库事件，例如pull/push 来自动触发；可以手动触发，还可以通过一些方式实现定时触发。

Events（事件）

事件就是触发 Workflow 运行的特定活动。例如 Pr, Push，新建 Issue等，也可以是定时任务，或者手动触发

Job （任务）和 Steps（步骤）

一个任务由一组 step 组合而成。每一个步骤 step 要么是一个 shell 脚本或者是一个 action。这组 steps 是按照顺序执行的，并彼此依赖。这些steps是在同一个 runner 中执行的，也因此你可以从某个step 中获取另一个 step 中的数据。例如，你可以在一个 build 任务后面，去创建一个测试任务以测试这个build 的产出。

一般来说，如果有多个 Job ，那么默认它们是并行的。但是如果某个 Job 的执行，依赖另一个 Job, 那么可以通过一定配置去描述，某个 Job A 的执行依赖于 Job B 的执行，这种情况下。 Job A 的执行就一定会在 Job B 执行之后才会执行。

Action（动作）

action 是Github Actions 平台的自定义应用程序，它们用于执行复杂但是经常重复的任务。通过引入这个 Action 可以极大的简化你的工作流配置。

Runner （运行机器）

一个 Runner 可以理解为一个运行 Workflow 的服务器。它可以是 Ubuntu Linux/ Windows/ MacOS。

二、快速开始

创建一个简单的 GitHub Actions Workflow

我们可以创建一个空的 Demo Git 仓库来演示一个最基础的 Workflow 长什么样子。

点击 [Action] 这个 Tab, 然后点击下方的 “set up a workflow yourself ”

拷贝下面的代码到编辑器中，然后点击 "Commit changes"：

在 Action Tab 中就能看到这个正在运行的 workflow 了：

点击可以看到具体的任务详情：

现在我们看看这份yaml 文件中的具体含义：

name: learn-github-actions
run-name: ${{ github.actor }} is learning GitHub Actions
on: [push] # 指定本 workflow 触发的事件为 Git push 事件
jobs: # 定义Jobs
  check-bats-version: # Job1 的名称，可以是任意的
    runs-on: ubuntu-latest # 指定runner 的环境
    steps: # 定义 steps
      - uses: actions/checkout@v4 # uses 指定了引用的 action, checkout 这个action 用于迁出，相当于在 runner 中去拉取一下本仓库代码
      - uses: actions/setup-node@v4 # node 配置 action
        with: # with 用于指定 action 的配置参数
          node-version: '20' # 配置参数 node-version, 值为 '20'
      - run: npm install -g bats # run 即在 runner 中cli 执行命令滚
      - run: bats -vcopy success

其中 "name" 和 "run-name" 的指定如下图：

这部分内容直接引用的 Github Actions 的官方文档，如果有不清楚的地方可以看官方的解释 link.

三、重用 Action

使用 Actions 市场中现成的 Actions

你可以直接在github 的编辑器中访问 Marketplace：

直接将 action 复制到编辑器：

你也可以直接访问 marketplace, 找到目标的 action, 再复制也行:

使用任何人 public 仓库的 actions

你可以通过 {owner}/{repo}@{ref} 语法去引用任何 public 仓库的 action:

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/setup-node@v4copy success

使用同仓库的actions

你还可以通过相对路径引用自己写的actions:

|-- hello-world (repository)
|   |__ .github
|       └── workflows
|           └── my-first-workflow.yml
|       └── actions
|           |__ hello-world-action
|               └── action.ymlcopy success

jobs:
  my_first_job:
    runs-on: ubuntu-latest
    steps:
      # This step checks out a copy of your repository.
      - name: My first step - check out repository
        uses: actions/checkout@v4
      # This step references the directory that contains the action.
      - name: Use local hello-world-action
        uses: ./.github/actions/hello-world-actioncopy success

注意 (./) 是相对于默认的工作目录（github.workspace, $GITHUB_WORKSPACE），如果 checkout 迁出的目录不是根目录，那么这个相对路径也需要调整

如果一个action发布在一个docker 镜像中，还可以引用这个docker 镜像，详细见 link, 这个用的不多，不做过多介绍。

四、高级用法

上下文的访问

你可以在这里看到，一个workflow 的执行，有很多的上下文，例如 github 的上下文， env 上下文， jobs上下文， steps 上下文， secrets 上下文。这个上下是一个非常重要的概念，我们知道，在代码编程时，也有一个上下文的概念，不同的作用域，上下文也不同。之所有会有这么多上下文，也是类似的。一个 workflow 的执行有很多子任务和环节。有的时候某个任务执行依赖另一个任务的产出，或者需要动态地获取到当前上下文的一些运行时信息。以确保任务的正常执行，上下文的存在同时也增强了 Github Actions 的灵活/功能性。

github 上下文

用途：提供关于仓库、事件、提交等信息

常见用法：

- name: Print repository
  run: echo "Repository: ${{ github.repository }}"

- name: Print event name
  run: echo "Event: ${{ github.event_name }}"

- name: Print SHA
  run: echo "SHA: ${{ github.sha }}"copy success

env 上下文

用途: 包含在工作流程中定义的环境变量。

常见用法：

env:
  MY_VAR: some value
steps:
  - name: Print environment variable
    run: echo "Env variable is ${{ env.MY_VAR }}"copy success

secrets 上下文
- 用途: 包含在仓库或组织中定义的秘密变量，用于存储敏感信息。
- 常见用法：
```
steps:
  - name: Use secret
    run: echo "Secret is ${{ secrets.MY_SECRET }}"copy success
```

vars 上下文

用途：全局的环境变量
常见用法：

name: learn-github-actions
run-name: ${{ github.actor }} is learning GitHub Actions
on: [push]
jobs:
  check-bats-version:
    runs-on: ubuntu-latest
    environment: test
    steps:
      - run: echo ${{vars.HELLO}}
      - run: echo ${{vars.JAYCE}}copy success

多 Job 和并行执行

name: learn-github-actions
run-name: ${{ github.actor }} is learning GitHub Actions
on: [push]
jobs:
  job1-check-test-vars:
    runs-on: ubuntu-latest
    name: Check Test Env Vars
    environment: test
    steps:
      - run: echo ${{vars.HELLO}}
  job2-check-vars:
    runs-on: ubuntu-latest
    name: Check Global Vars
    steps:
      - run: echo ${{vars.JAYCE}}

  # job3 的执行依赖 job1 的先执行
  job3-check-runtime-env:
    runs-on: ubuntu-latest
    name: Check Runtime Env
    needs: [job1-check-test-vars]
    env:
      SAY_HI: Hi ~~~
    steps:
      - run: echo ${{env.SAY_HI}}

  job4-echo-string:
    runs-on: ubuntu-latest
    name: Echo String
    needs: [job1-check-test-vars]
    steps:
      - run: echo "just echo a string~"copy success

条件执行和矩阵构建

缓存和依赖管理

定时任务和事件触发

五、实战案例

自动化测试流程

持续集成和持续交付CICD

自动发布和部署

六、常见问题与解决

调试和日志查看

常见错误以及解决方案

七、最佳实践

安全性注意实现

性能优化

社区资源和学习路径

八、总结

仿做一个 Chrome Bookmarks

SunZhongyi — Thu, 18 Jul 2024 00:00:00 GMT

我算是 Google Chrome Bookmarks 的重度依赖用户了。今天偶然看了下实现源码，发现它是用原生 JS 写的，而且采用面向对象的工程化思想写的。想着多看看，学习学习，那么最好的方式当然就是抄一个了。

一、项目初始化

直接用 omed 来启动一个原生项目：

dm ChromeBookmarkscopy success

先做一个基本的布局：

<div id="app">
  <header class="bg-slate-500 h-12">header</header>
  <main class="h-screen">
    <aside class="bg-slate-700">aside</aside>
    <div class="main-content bg-slate-800">content</div>
  </main>
</div>copy success

为了样式结构更清晰，我们使用 sass

$header-height: 3rem;
#app {
  header {
    height: $header-height;
  }
  main {
    height: calc(100vh - $header-height);
    display: flex;
    aside {
      min-width: 256px;
      max-width: 40%;
    }
    .main-content {
      flex: 1;
    }
  }
}copy success

拖拽条

可以看到 Chrome Bookmarks 中的侧边栏支持拖拽

为什么不直接使用 resize css 属性呢？我们自己尝试一下：

    aside {
+    resize: horizontal; /* required */
+    overflow: auto; /* required */
      min-width: 256px;
      max-width: 40%;
+   &:hover {
+      border-right: 1px solid red;
+   }
    }
copy success

可以发现，只有拖拽元素的右下角的 Handler 才行，元素的边缘部分是不行的。

那 Chrome Bookmarks 是怎么做的呢？

可以看到，它做了一个单独的 15 像素宽的分割条。并且是一个自定义元素，那它是怎么做的呢？

如何创建一个自定义元素？

创建一个自定义元素通过 window.customElements.define 方法来实现 MDN 。

// 语法
define(name, constructor)
define(name, constructor, options)copy success

其中 name 的命名有一定要求，简单来说就是小写字母开头，并且必须包含一个中划线 -, 还有一些被占用的元素不可用，详细看这里 link.

下面写一个示例：

拖拽条的实现

作为开头，我们直接看看 Chrome Bookmarks 是怎么做的吧，来看看怎么找到对应的源代码：

先给这个拖拽条打个断点：

拖动一下，就会跳转到源代码对应行：

我这里直接将对应的代码拷贝过来，然后转写一下为 Typescript，虽然能跑，但是一片红。

为了工程化实践，我们将它模块化：

然后在页面中引入它：

试一下：

Working Perfect !

不过不是自己写的，接下来研究下它怎么实现的，怎么做到的如此解耦，单一个自定义元素就搞定了。

首先我们应该带着一点想法和问题，这样才好理解它的源代码。

如果我们自己实现，大致应该是一个什么过程？好像其实挺简单

监听这个拖拽条的拖拽事件，然后获取拖动的 DeltaX 的值，然后不断在拖动过程中去更新前面这个 aside 元素的值。

See the Pen DragBar_IMPL[blog] by joisun (@joisun) on CodePen.

短短几行，我们其实就可以实现了，但是 Chrome Bookmarks 的实现，该自定义元素的代码高达 130 行

可能是不想有这个默认的东西？

或者是考虑一些兼容性问题？性能？健壮性？

确实是这样的，他的实现逻辑首先是兼容了触屏设备的 touch 事件，以及 mouse 事件。然后统一派发处理逻辑。只不过它做了更多的额外处理。例如兼容阿拉伯语系 RTL 排版:

// 做兼容性处理， 默认浏览器的文字排版时从左到右， 但是有一些国家，例如阿拉伯语国家， 是从右到左， 这时候的 deltaX 的计算规则不同。
// this指的是当前元素实例， 元素实例上的 matches 方法用于匹配css选择器。
const deltaX = this.matches(':host-context([dir=rtl]) cr-splitter') ? this.startX_ - clientX : clientX - this.startX_copy success

广播 drag 相关事件：

// ......
this.dispatchEvent(new CustomEvent('dragmove'))
// ......
this.dispatchEvent(new CustomEvent('resize'))copy success

其他的逻辑其实和我们上面的 demo 实现原理是一样的。

不过他的实现中，有一些设计和逻辑指的学习：

首先这种自定义元素的设计有什么好处？ ——> 解构

通过这种方式，所有和这个拖拽条相关的事件逻辑处理都在这个类中处理。如果外部需要相关事件，就通过派发自定义事件，然后其他的需要消费的地方监听就可以了
在拖拽条这个元素内部，他是怎么做到调整的 aside 元素的宽度的？

他用到了一个我们平常很少用到的属性。previousElementSibling, 具体的它是通过 getResizeTarget_ 这个函数拿到的。
```
getResizeTarget_() {
    const target = this.resizeNextElement ? this.nextElementSibling : this.previousElementSibling;
    return target as HTMLElement | null
}copy success
```
resizeNextElement 是构造器中的值，为了获取拖拽条左边或者右边的元素，他在构造器中初始化。这可能是一种扩展性设计，防止未来如果布局 aside 元素移动到拖拽条右边的情况，只需要改一下这个布尔值就可以了。

nextElementSibling 这个可能还用过，就是拿到后面的相邻元素，previousElementSibling 就是拿前面的元素。

更新中...

来玩一玩 View Transition API

SunZhongyi — Mon, 22 Jul 2024 00:00:00 GMT

一、引入

相信作为前端的你，一定好奇过下面这种动画效果是怎么实现的：

小红书

Apple App Store

Instagram

这些动画其实有一个专门的描述词，叫做 共享元素转场 (Shared Element Transition)，或者叫做 英雄动画 (Hero Animation)

这种动画效果的主要特点是元素看起来像是从一个页面"飞"到另一个页面，而不是突然消失再出现。给人的直观感受就是非常的丝滑流畅，视觉上连续性很强。

这么做在用户体验设计上来说，是一种非常友好的设计。主要方面在于：

空间关系：视觉的连续性可以帮助用户理解两个页面之间的空间关系。
焦点引导：引导用户的注意力从一个视图到另一个视图。

接下来，我们将通过学习 View Transition API 来实现类似的过渡动画效果。

一、View Transition API 的概念

我们知道，在同一个页面上，我们有很多的方式去实现元素的动画效果。例如纯CSS 动画，或者是像一些 CSS 动画库, 如 animate.css；又或者像 Gsap 这种强大的 JS 动画库。然是，通常来说，如果想要实现跨页面的动画过渡，会尤其的麻烦，需要开发者手动的维护很多的额外代码。例如处理新旧页面的元素的位置，根据新旧页面去创建复杂动画等等工作量。

但是现在， View Transition API 提供了一种简单的方式，让用户实现跨页面的过渡动画。 View 即视图， View transition 就是视图过渡。视图的过渡，包括 SPA，和 MPA 应用。

View Transition API 的实现原理

视图过渡伪元素

首先，重新理解一下过渡动画，什么是过渡动画呢？简单的来说，过渡动画常规理解，就是一次页面瞬时的变化的前后，应用动画的过程。换句话说，过渡动画就是是从一个新的页面视图，通过某种动画过渡到一个新的页面视图。

那么，基于此，要想处理这两个状态中间的过渡态，我们就需要一种机制，能够同时处理这个两个新的视图状态。换言之，至少我得能访问到新旧的页面视图，我才能进行动画过渡的处理。这个在 SPA 应用中可能好理解，也相对容易实现。不过 MPA 怎么办呢？页面直接就刷新了。而不是 SPA 中的路由跳转模拟的局部刷新。

为了解决这个问题，所以构建了一种新的伪元素。用于保存新旧视图的状态。就是 视图过渡伪元素。我们通常管视图的状态叫做快照。核心的视图过渡伪元素就两个，分别是 ::view-transition-old(view-transition-name) 和 ::view-transition-new(view-transition-name)。

和普通的 DOM元素相比较而言，它们特殊之处在于：

它们专门用于处理视图过渡动画
它们仅在视图过渡期间短暂的存在，随后被立即销毁
也可以通过 CSS 指定样式

@joisun: 上面提到了 SPA 和 MPA，可不要对 SPA 有过多的猜测， View Transition API 机制的设计是框架无关的，并且，所谓 SPA 其实往简单了说，就是一个大一点的单个 html 文件罢了。也就意味着，该 API 理论上同样可以实现普通的过渡动画。只要页面视图发生了变化。

视图过渡伪元素树

The view transition pseudo-element tree

View Transition API 实现从当前页面到新页面的过渡机制是围绕一棵伪元素树来实现的。这棵树的结构如下：

::view-transition # 整个过渡效果的根元素，覆盖在页面内容之上
└─ ::view-transition-group(root) # 每个过渡快照组的容器
  └─ ::view-transition-image-pair(root)
      ├─ ::view-transition-old(root) # 旧页面元素的静态快照
      └─ ::view-transition-new(root) # 新页面元素的实时快照

# 默认情况下，root 指的是 :root 元素, 可以通过 CSS属性 view-transition-name 更改默认的 root 元素
# 例如：
:root{
	view-transition-name: app
}copy success

View transition（视图过渡）的工作过程

在了解了一些基本的前置概念和原理后，我们可以看看一次视图过渡过程，将会如何被 View Transition API 处理。

触发视图过渡：通过 document.startViewTransition() 方法触发；
当前（旧）视图捕获快照：API 捕获带有view-transition-name 声明的元素快照, (::view-transition-old)。
发生 视图变更：响应用户操作，将具体更新DOM的事件交给 API，放在 startViewTransition() 的回调函数中在适当时机去自动执行, 例如路由跳转。注意并不只是路由跳转，任何会引起页面更新的事件都可以。
动画准备阶段：
- API从新视图捕获快照, 也就是记录为 ::view-transition-new。
- ViewTransition.ready 这个 Promise fulfill 表示准备就绪，即将开始动画。
  
  ⚠️注意：这时，开发者可以取消默认动画，实现自定义动画。
过渡动画执行 (默认动画)：
- 旧视图快照动态淡出（opacity从1到0）,新视图快照动态淡入（opacity从0到1）。
过渡完成：动画结束后 (ViewTransition.finished)，可以响应完成事件。

这个过程中有几个点值得注意：

整个过程中，ViewTransition 对象提供了多个Promise（如updateCallbackDone、ready、finished），允许在过渡的不同阶段执行代码。
跨文档(MPA)过渡，不同于同文档(SPA)过渡, 视图过渡的触发是通过导航到新文档而触发的，并且需要同源并在CSS中包含 @view-transition规则
再就是第3步，也就是 “视图变更”，跨文档(MPA)过渡, 就是在当前和目标文档间进行导航，而不是同页面元素状态的更新。

现在，让我们看看具体的实例吧！

二、View Transition API 的示例

在 MDN 的文档中给出了两个很简单的示例，我们可以简单的看一看。

Gallery 页面

该页面的程序逻辑部分，大致是这样的：

// 初始化
function init() {
  // 创建元素， 初始化页面图片，事件绑定等
}

// 处理用户点击
function updateView() {
  const displayNewImage = () => {
    // 更新img 的 src 属性 +  更新 caption 描述
  }

  // 核心
  const transition = document.startViewTransition(() => displayNewImage())
}copy success

可以看到程序部分相当简单，就一行核心代码，就是把视图更新的具体函数，放到 startViewTransition 的回调中交给 API 的执行。

再看看样式部分：

/* View Transitions CSS */
::view-transition-group(root) {
  animation-duration: 0.5s;
}
figcaption {
  view-transition-name: figure-caption;
}
/* Simple final style */
::view-transition-group(figure-caption) {
  height: 100%;
}copy success

可以看到，相关的样式部分也非常简单。

我其实认为这个示例并不好，徒增了新的学习者的理解成本。让我们单独来看吧，更容易理解。

首先：

::view-transition-group(root) {
  animation-duration: 0.5s;
}copy success

这里是指定 root 元素的过渡动画时长。这个 root 是什么呢？它其实指的是名为 "root" 的 view-transition-name 的目标元素。它是整个文档根元素，也就是 document 元素(html)。 API 通过这种方式记录需要过渡的元素。这里省略了一个默认设定：

:root {
  view-transition-name: 'root';
}copy success

这下一眼就能明白了吧，上面那行代码实际上是在指定整个 document 元素的动画时长。

紧接着：

figcaption {
  view-transition-name: figure-caption;
}copy success

这里是在通过 view-transition-name 给 <figcaption> 这个需要过渡动画的元素定义一个视图过渡名称。你可以为任何选择器的元素指定一个视图动画，例如指定某个 id 名为 "list-item-1" 的 <li> 元素:

li#list-item-1 {
  view-transition-name: any-name-you-want;
}

/* 你还可以覆盖默认的动画名称 */
:root {
  view-transition-name: app-blog;
}copy success

值得注意的是定义 view-transition-name 必须是全局唯一的。

最后的：

::view-transition-group(figure-caption) {
  /* 这里指定的是figure-caption 这个视图过渡动画组的样式，会在整个过渡动画过程中生效 */
  height: 100%;
}copy success

不过这里的 height:100% 并不明显，让我们做一些修改，看看会如何表现：

::view-transition-group(figure-caption) {
  /* height: 100%; */
  border: 4px solid red;
}copy success

你看到了吗，我们设定的 border 样式会作用于整个过渡周期。包括新旧目标元素。

你观察到了动画效果吗，目前全部都是默认的动画效果 cross-fade 交叉淡出淡入，不过如果你观察的更仔细一点，你可能会发现这个 figurecaption 元素的高度和宽度似乎也参与到了动画。确实，这是因为 ::view-transition-group 也有默认动画 (#refer)，它包括了 position, height,width。

MPA 页面跳转

这个示例保持了最简单的情况，没有 Js 程序逻辑部分。两个页面的样式也是一样，让我们看一看：

/* Turn cross-document view-transitions on */
/* Note that this at-rule is all that is needed to create the default cross-fade animation  */
@view-transition {
  navigation: auto;
}
/* Customize the default animation behavior */
::view-transition-group(root) {
  animation-duration: 0.5s;
}
/* Create a custom animation */
@keyframes move-out {
  from {
    transform: translateY(0%);
  }
  to {
    transform: translateY(-100%);
  }
}
@keyframes move-in {
  from {
    transform: translateY(100%);
  }
  to {
    transform: translateY(0%);
  }
}
/* Apply the custom animation to the old and new page states */
::view-transition-old(root) {
  animation: 0.4s ease-in both move-out;
}
::view-transition-new(root) {
  animation: 0.4s ease-in both move-in;
}copy success

首先，在两个页面中，都需要先开启页面过渡

@view-transition {
  navigation: auto;
}copy success

然后定义了一套 css 动画，动画就是新的页面从底部移入，旧的页面从上面移出。

可以看到， MPA 的过渡动画设定非常简单，甚至都不需要用到 JS 逻辑。

但是我们也容易发现这个动画割裂感挺重的，原因他们的动画都是一样的，我们可以做一些优化。

例如从 A -> B 页面时（A页面中），我们让即将跳转的新的视图B 从下面移入，然后当前页面A，也就是即将变做旧的视图从视口上面移出。在从 B -> A 页面时（B页面中），我们让新的视图 A从上面移入，让旧的视图 B 从下面移出。关键代码如下：

/* Page A */

/* Turn cross-document view-transitions on */
@view-transition {
  navigation: auto;
}

/* Customize the default animation behavior */
/* ::view-transition-group(root) {
    animation-duration: 0.2s;
} */

/* Create a custom animation */
@keyframes top-move-out {
  from {
    transform: translateY(0%);
  }

  to {
    transform: translateY(-100%);
  }
}

@keyframes bottom-move-in {
  from {
    transform: translateY(100%);
  }

  to {
    transform: translateY(0%);
  }
}

/* Apply the custom animation to the old and new page states */
::view-transition-old(root) {
  animation: 0.4s ease-in top-move-out;
}

::view-transition-new(root) {
  animation: 0.4s ease-in bottom-move-in;
}

/* Page B */
a {
  color: rgb(124, 124, 255);
  font-size: 2rem;
}

/* Turn cross-document view-transitions on */
@view-transition {
  navigation: auto;
}

/* Customize the default animation behavior */
/* ::view-transition-group(root) {
    animation-duration: 0.2s;
} */

/* Create a custom animation */
@keyframes bottom-move-out {
  from {
    transform: translateY(0%);
  }

  to {
    transform: translateY(100%);
  }
}

@keyframes top-move-in {
  from {
    transform: translateY(-100%);
  }

  to {
    transform: translateY(0%);
  }
}

/* Apply the custom animation to the old and new page states */
::view-transition-old(root) {
  animation: 0.4s ease-in bottom-move-out;
}

::view-transition-new(root) {
  animation: 0.4s ease-in top-move-in;
}copy success

你可以在这里看到页面效果 link, bak. 可以在这里看到源码.

三、在流行框架中使用 View Transition API

大多框架中的路由导航是异步执行的：

document.startViewTransition(() => {
  router.jump('xxxx')// 这里通产是异步的
})copy success

然而 document.startViewTransition 期望在其回调函数中立即发生 DOM 变化。

下面我们来尝试看看分别在 React 和 Vue 中去尝试实现。

项目初始化

分别初始化两个最基本的项目，React 因为之前 omed 配置过一个router+tailwind 的最简模板，我们就使用它来创建。 Vue 就直接 pnpm create vite@latest 。

# react
dm view-transition-demo-react
# vue
pnpm create vite@latest view-transition-demo-vuecopy success

简单的初始化项目，这个项目有两个路由页面，分别是首页和详情页，点击首页中的列表项，就会跳转到详情页面：

接下来的探究中，我们只关心最核心的部分逻辑就好：

React

快速尝试

给首页的 <img> 元素注册了点击事件，

const handleClick = (i: number, e: React.MouseEvent<HTMLImageElement>) => {
    document.startViewTransition(() => {
        navigate(`/detail/${i}`)
    })
}copy success

给详情页的返回按钮注册返回事件

function handleBack() {
  document.startViewTransition(() => {
    navigate(-1)
  })
}copy success

来试试看，会发生什么：

没错默认的 root view transition 动画(cross-fade) 被触发了

给img加上单独的动画

现在我们尝试给 img 元素添加单独的动画效果。首先，在全局的样式表中，定义一个 view-transition-name,

/* global.css */
.dog-card {
  view-transition-name: dog-card;
}copy success

注意，这里 .dog-card class 选择器匹配的是详情页中的那个 img 元素：

<img className="dog-card ..........copy success

还记得吗，view-transition-name 前面说过了，它必须全局唯一。我们首页中，img 元素是一个列表遍历结果。

{
    Array.from({ length: 16 }).map((_, index) => (
        <div className="item " v-for="(image, index) in 16" key={index} >
            <img ......./>
copy success

所以我们不能直接给所有 img 元素加上 view-transition-name: dog-card 这个css 属性。我们可以动态的添加，

在首页点击 img 元素的事件handler中：

const handleClick = (i: number, e: React.MouseEvent<HTMLImageElement>) => {
    const target = e.target as HTMLImageElement
    (target.style as any).viewTransitionName = 'dog-card'
    document.startViewTransition(() => {
        navigate(`/detail/${i + 1}`)
    })
}copy success

现在，来看看效果如何：

为什么没有生效呢？

原因是现代框架中，对页面渲染，各框架通常都做了不同的优化。在 React 中，React 的状态更新和渲染是使用虚拟DOM 和批量更新机制来优化性能。当我们这里调用 navigate 的时候， React 并不会立即更新 DOM，而是将更新放入队列中，等待下一个渲染周期。

而 View Transition API 的工作方式是它期望在其回调函数中立即发生 DOM 变化。因此，在 React 完成页面更新的时候可能都已经结束了。自然就不生效了。

那么同理的，在 Vue 中也是会遇到这种情况。

不过在 React-Router中，很早就有人提到过这个问题 issue#10276, 官方页给出了两种解决方案。

使用 flushSync 包裹 navigate 让其强制同步更新
给 navigate 传入一个 unstable_viewTransition option，让React-Router 内部去黑盒操作。

我们来试一试：

 const handleClick = (i: number, e: React.MouseEvent<HTMLImageElement>) => {
     const target = e.target as HTMLImageElement
     (target.style as any).viewTransitionName = 'dog-card'
     document.startViewTransition(() => {
-       navigate(`/detail/${i}`)
+       navigate(`/detail/${i}`, { unstable_viewTransition: true })

+ //    或者也可以像下面这样写
+ //    flushSync(
+ //        ()=>navigate(`/detail/${i}`)
+ //    )
     })
 }
copy success

生效了，且由于默认的 ::view-transition-group(dog-card) 动画，让图片元素的位置和大小自动的过渡了。

不过不难发现，返回的时候，动画好像还是默认的 cross-fade 动画，这是为什么呢？

其实很好理解，详情页中，.dog-card 匹配的元素是固定的，但是首页中，为了避免 view-transition-name 重复，所以我们是在点击的时候动态添加的

 (target.style as any).viewTransitionName = 'dog-card'copy success

因此，从首页过渡到详情页的时候，新旧元素的快照都能够顺利找到，自然可以开启过渡动画了。但是，从详情页返回到首页的时候，之前标记 'dog-card' view-transition-name 的元素由于更新，是消失了的。

所以要解决这个问题，我们就需要记住当前点击的这个卡片是哪一个，然后在返回的时候，先给这个卡片再次设定一下 view-transition-name，那么该怎么做呢？

其实很简单，把这个状态存下来，不管用什么方式，我们这里图方便，就直接放 sessionStorage 好了，我们更新一下 handleClick

const getCache = ()=>{
    return +(sessionStorage.getItem('cache-dog-card-index')||0)}
console.log('getCache',getCache())

const handleClick = (i: number, e: React.MouseEvent<HTMLImageElement>) => {
    // 将当前点击图片的索引存储在 sessionStorage 中
    // 这使我们能在从详情页返回时恢复 view-transition-name，确保平滑的过渡动画
    sessionStorage.setItem('cache-dog-card-index', i + '')

    // 清除所有图片现有的 view-transition-name
    // 这么做是因为：
    // 1. view-transition-name 必须在全局范围内唯一
    // 2. 我们需要为新点击的图片设置新的 view-transition-name
    // 3. 这可以防止在为新目标设置 viewTransitionName 时出错
    for (let img of document.querySelectorAll('img')){
        (img.style as any).viewTransitionName = 'unset'
    }

    // 为被点击的图片设置 view-transition-name
    const target = e.target as HTMLImageElement
    (target.style as any).viewTransitionName = 'dog-card'
    document.startViewTransition(() => {
        navigate(`/detail/${i}`, { unstable_viewTransition: true })
    })
}copy success

注意：viewTransitionName 尚未标准化，ts还不认识，所以我们使用 'any' 类型断言

然后在 Dom 上：

// ......
                {
                    Array.from({ length: 16 }).map((_, index) => (
                        <div className="item " v-for="(image, index) in 16" key={index} >
                            <img  style={ getCache() === index+1 ? {viewTransitionName:'dog-card'} : {}}
// ......
copy success

每次首页更新，我们都尝试从缓存中恢复之前记录的索引，为目标元素恢复 view-transition-name: dog-card 的设定。

不必担心 viewTransitionName 不唯一，你还记得吗，刚才，我们在 handleClick 中已经清除了所有的 img 元素的 viewTransitionName, 这样就能够保证页面在从详情页返回的时候，View Transition API 能够顺利找到 ::view-transition-new(dog-card) 伪元素了，从而让过渡动画顺利执行。

现在我们再来看看效果吧。

完美！！！ demo, 完整代码。

当然，由于 View Transition API 动画是CSS 实现的，所以你还可以根据 css 动画库，比如 animate.css 来实现一些奇奇怪怪的效果：

.dog-card {
    view-transition-name: dog-card;
}

::view-transition-group(dog-card) {
    animation-duration: .3s;// 整体动画时长，会被具体的 new/old 设定覆盖
}

::view-transition-old(dog-card),
::view-transition-new(dog-card) {
    animation: .3s scale both;
    -webkit-animation-duration: 1.3s;
    animation-duration: 1.3s;
    -webkit-animation-duration: 1.3s;
    animation-duration: 1300ms;
    -webkit-animation-name: heartBeat;
    animation-name: heartBeat;
    -webkit-animation-timing-function: ease-in-out;
    animation-timing-function: ease-in-out
}

@keyframes heartBeat {
    0% {
        -webkit-transform: scale(1);
        transform: scale(1)
    }

    14% {
        -webkit-transform: scale(1.3);
        transform: scale(1.3)
    }

    28% {
        -webkit-transform: scale(1);
        transform: scale(1)
    }

    42% {
        -webkit-transform: scale(1.3);
        transform: scale(1.3)
    }

    70% {
        -webkit-transform: scale(1);
        transform: scale(1)
    }
}copy success

Vue

Vue 有点问题，Vue-router 好像只能异步执行，官方似乎没有支持。提了个 Discussion, 等我发现了解决方案再来更新这部分内容。另外 View Transition API 还不是标准阶段，一些浏览器还没有兼容，这个特性目前并不适合生产使用。如果你生产项目中有需要可以看看这个 antfu/vue-starport。

快速尝试

 const handleClick = (i: number) => {
+    document.startViewTransition(() => {
         router.push(`/detail/${i}`)
+    })
 }
copy success

先不管这个 API 什么意思，我们看看现在的页面有什么效果变化吗

可以看到会有一个简单的过渡效果，看上去是透明度 + 叠加的变化效果。这是 View Transition API 的默认过渡效果。显然这并不能达到我们期望的效果。所以接下来，让我们详细认识一下这个 API，以及如何实现我们需要的效果。

待更新内容......

四、不止路由过渡动画——实现和 Element Plus 一样的主题切换动画效果

不知道你是否有留意过 element plus 官方文档的主题切换效果？

其实它就是借助于 View Transition API 来实现的，让我们也来试试吧。

先用 omed 起一个 vanilla 项目：

dm view-transition-demo-elementpluscopy success

然后实现一个最基本的主题切换效果：

主题切换按钮的 Handler很简单：

function handleThemeSwitch() {
    isDark = document.documentElement.classList.toggle('dark')
}
// switch button click handler
function handleClick(e: MouseEvent) {
    handleThemeSwitch()
}copy success

然后利用 transition.ready 这个 API 结合 animate 去创建我们自定义的动画。

function handleClick(e: MouseEvent) {
    // 兼容性处理
    if (!(document as any).startViewTransition) {
        handleThemeSwitch()
        return;
    }

    // 获取点击事件位置
    const x = e?.clientX ?? innerWidth / 2;
    const y = e?.clientY ?? innerHeight / 2;
    // 计算最大半径
    const endRadius = Math.hypot(
        Math.max(x, innerWidth - x),
        Math.max(y, innerHeight - y),
    );

    // 创建过渡
    const transition = (document as any).startViewTransition(() => {
        console.log("trigger")
        handleThemeSwitch()
    });

    // 等待伪元素创建
    transition.ready.then(() => {
        // 自定义动画执行
        document.documentElement.animate(
            {
                clipPath: [
                    `circle(0 at ${x}px ${y}px)`,
                    `circle(${endRadius}px at ${x}px ${y}px)`,
                ],
            },
            {
                duration: 400,
                direction: isDark ? 'reverse' : 'normal',
                easing: "ease-in",
                // 指定目标动画伪元素
                pseudoElement: "::view-transition-new(root)",
            },
        );
    });
}copy success

不过现在看起来有些奇怪，切换的时候被遮住了，加点盐：

::view-transition-old(root),
::view-transition-new(root) {
  /* 这行代码禁用了默认的过渡动画 */
  animation: none;
  /* 设置了元素的混合模式为"正常" */
  mix-blend-mode: normal;
}copy success

撸一个纯前端实现的FFmpeg视频转压缩工具

SunZhongyi — Tue, 30 Jul 2024 00:00:00 GMT

一、引言

写文章的时候，有的地方为了描述，或者演示清楚，所以经常需要准备一些GIF/WEBP 的短视频演示素材插入文中。经常会用到 FFmpeg 这个命令行工具，不过尽管用了很久，我始终是记不住这些参数命令，太多了主要是。我甚至写过一篇文章去结构性的总结使用 FFmpeg ---- 《FFmpeg的安装和基本使用》。

之所以我不用现有的视频剪辑工具，主要原因还是觉得臃肿。

我一开始本来只是想做个界面，动态的帮我拼接生成指令，然后粘贴到命令行去使用。

不过做完了，想着现在不是有 wasm 吗？直接放浏览器里面跑不是更省事？

技术栈的选择

React：为了练习使用 React，所以这次就选用 React 来撸吧
shadcn-ui: 一个 UI 库
FFmpeg.wasm：FFmpeg的WebAssembly版本，使得在浏览器中运行FFmpeg成为可能。
TypeScript：没什么好提的
react-hook-form：用于处理表单状态和验证的React库
zod：TypeScript优先的模式声明和验证库

一些技术，像 react-hook-form 和 zod，我之前完全没用过，不过现在我和 AI 结对编程，基本上也是磕磕绊绊用起来了，之前的工作中也没用到过，就当拓展一下认识了。

这个项目本身来说，就是一个小工具，在做之前先整理下思路，就两个点：

首先，我得拼出命令行可用的指令串。
让它在浏览器中去执行

本文也只是从大致实现上去描述一下，所以不会逐行实现，感兴趣的朋友可以自行翻源码 joisun/ffmpeg-convertor，有更多想法的话，也欢迎 PR。

演示地址:https://ffmpeg-convertor.vercel.app/

构建 UI

表单设计与验证

我们使用react-hook-form和zod来处理表单。首先，定义了一个formSchema，它描述了表单的结构和验证规则：

const formSchema = z.object({
  fps: z.coerce.number().lte(120).gte(10),
  width: z.coerce.number().lte(5000).gte(1),
  loop: z.coerce.number().gte(0),
  bitrate: z.string().min(0),
  compression: z.coerce.number().lte(100).gte(0),
  output: z.string().min(1).max(50).regex(/^[\w-]+$/),
  // ... 其他字段
})copy success

这个schema不仅定义了每个字段的类型，还包含了详细的验证规则，如最大/最小值、正则表达式匹配等。

表单组件

使用useForm钩子初始化表单，并设置默认值：

const form = useForm < z.infer < typeof formSchema >> ({
  resolver: zodResolver(formSchema),
  defaultValues: {
    fps: 30,
    width: 480,
    loop: 0,
    bitrate: '800k',
    // ... 其他默认值
  },
})copy success

然后用 Shadcn-ui 的 Form 组件去构建 UI：

// ......
<Form {...form}>
        <form
          onSubmit={form.handleSubmit(() => onSubmit(form.getValues(), false))}
          className="sm:grid lg:grid-cols-2 xl:grid-cols-3 2xl:grid-cols-4 gap-x-4 gap-y-4"
        >
          <FormField
            control={form.control}
            name="fps"
            render={({ field }) => (
              <FormItem>
                <FormLabel>帧率</FormLabel>
                <FormControl>
                  <Input type="number" placeholder="" {...field} />
                </FormControl>
                <FormDescription>控制输出资源的帧率</FormDescription>
                <FormMessage />
              </FormItem>
            )}
          />
          <FormField
// ......
copy success

文件上传与预览

使用自定义的Dropzone组件处理文件上传，VideoClipper组件用于视频预览和裁剪：

组件代码的实现可自行翻阅源码

<Dropzone
  onChange={handleDropzoneChange}
  className="w-full h-24 my-12 flex items-center justify-center"
  fileExtension="video/*"
/>

<VideoClipper src={videoSrc} onClipChange={handleVideoClipperChange}>
  {/* ... */}
</VideoClipper>copy success

到这里，基本的用户界面就算构建完成了。接下来就是接入 FFmpeg 了。

接入 FFmpeg

在浏览器中使用 FFmpeg，就需要借助 wasm 的实现，我们使用 ffmpeg.wasm。

为了我们使用方便，我们采用 React Hook 的方式对它进行一些封装：

这个 hook 将导出一个对象，其中包括了一些状态，还有一个 transcode 方法。该方法用于执行对文件的转换。

interface FFmpegInstance {
    load: () => Promise<void>;
    transcode: (file: File, commandParts: CommandPartsType) => Promise<void>;
    isLoaded: boolean; // 是否加载完成
    isDoing: boolean;// 是否正在执行转换任务
    isLoading: boolean;// 是否正在加载
    progress: number;// 转换任务处理进度
    transcodedTime: number; // 转化的产物时长
    logs: string[];//执行期间的日志
    error: Error | null;//错误
    openMT:boolean;// 是否开启了多线程
}copy success

FFmpeg.wasm 的接入有一些注意点，FFmpeg.wasm 官方提供了两种包：

多线程支持
单线程

对于多线程支持，需要用到 SharedArrayBuffer ，是 JavaScript 中的一个对象，它代表一个固定长度的原始二进制数据缓冲区，可以在多个工作线程（Web Workers）之间共享。

不过由于它支持多个线程操作同一个内存空间，处于安全考虑，通常需要网站实施特定的安全头才能启用也就是：

'Cross-Origin-Embedder-Policy': 'require-corp',
'Cross-Origin-Opener-Policy': 'same-origin',copy success

单线程则没有这些要求。不过单线程相对多线程肯定是要慢很多。

另一个问题就是多线程并不是所有浏览器都支持，似乎目前 Chromium based 的浏览器都不支持。这也就意味着， Chrome, Safari, 还有一众过程套壳的浏览器都不支持。好消息是 FireFox 支持。

为此，我们需要做一个自动启用，去自动切换这两种模式。下面是核心的部分代码：

// 检测当前浏览器环境是不是 FireFox， 如果是就把  OpenMT 这个开启标志设为 true
const browser = Bowser.getParser(window.navigator.userAgent)
let OpenMT = false
if (browser.getBrowser().name === 'Firefox') {
  OpenMT = true
}
serOpenMT(OpenMT)

//  根据 OpenMT 的值自行加载 对应 的 FFmpeg.wasm 模块。
const CORE_URL = 'https://cdn.jsdelivr.net/npm/@ffmpeg/core@0.12.6/dist/esm'
const CORE_MT_URL = 'https://cdn.jsdelivr.net/npm/@ffmpeg/core-mt@0.12.6/dist/esm'
const baseURL = OpenMT ? CORE_MT_URL : CORE_URL
await ffmpegRef.current.load({
  coreURL: await toBlobURL(`${baseURL}/ffmpeg-core.js`, 'text/javascript'),
  wasmURL: await toBlobURL(`${baseURL}/ffmpeg-core.wasm`, 'application/wasm'),
  ...(OpenMT
    ? {
        workerURL: await toBlobURL(
          `${baseURL}/ffmpeg-core.worker.js`,
          'text/javascript'
        ),
      }
    : {})
})copy success

这部分代码，官方也是这么干的。可以看看官方的 Playgroud。对应的源码在 here.

另外，在开发阶段，vite.config.ts 中需要配置响应头：

optimizeDeps: { exclude: ["@ffmpeg/ffmpeg", "@ffmpeg/util"], },
server: {
headers: {
  'Cross-Origin-Embedder-Policy': 'require-corp',
  'Cross-Origin-Opener-Policy': 'same-origin',
},
}copy success

在部署阶段，因为我使用的是 vercel 部署的， vercel 暴露了 vercel.json 配置文件，可以很方便的支持我们自行配置，如下：

// vercel.json
{
  "headers": [
    {
      "source": "/",
      "headers": [
        {
          "key": "Cross-Origin-Embedder-Policy",
          "value": "require-corp"
        },
        {
          "key": "Cross-Origin-Opener-Policy",
          "value": "same-origin"
        }
      ]
    },
    {
      "source": "/assets/(.*)",
      "headers": [
        {
          "key": "Cross-Origin-Embedder-Policy",
          "value": "require-corp"
        },
        {
          "key": "Cross-Origin-Opener-Policy",
          "value": "same-origin"
        }
      ]
    }
  ]
}copy success

完整的 useFFmpeg Hook 实践，详见源码.

FFmpeg命令生成与执行

定义了onSubmit函数来处理表单提交。它首先生成FFmpeg命令，然后根据需要执行转码：

async function onSubmit(values: z.infer<typeof formSchema>, onlyGenerateCommand?: boolean) {
  const { command, commandParts } = generateFFmpegCommand({
    ...values,
    timeRange,
    input: sanitizeFilename(files[0].name)
  });
  setCommand(command);
  if (onlyGenerateCommand) return;

  await handleTranscode(files[0], commandParts);
}copy success

到这里基本就完成了。

然后处理一些用户反馈的 UI 和逻辑，这里就不展开说明了。来看看具体怎么使用这个工具。

使用

访问 https://ffmpeg-convertor.vercel.app

开始之前，你可以在这里看到应用的基本状态：

上传视频：打开应用后，您会看到一个拖放区域。只需将视频文件拖入其中，或点击选择文件即可上传。

视频预览和裁剪：上传完成后，视频会自动显示在预览区域。您可以使用内置的视频裁剪工具选择所需的片段。

设置转换参数：

帧率（FPS）：控制输出视频的流畅度，通常在10-120之间。
宽度：设置输出视频的宽度，高度会按比例自动调整。
循环次数：设置GIF等格式的循环播放次数，0表示无限循环。
比特率：控制视频质量和文件大小的平衡，可从预设选项中选择。
压缩级别：滑动条可调节0-100，数值越高压缩越大，文件越小但质量越低。
抽帧：控制每隔多少帧选取一帧，用于创建缩时效果。
颜色空间：根据需要选择适当的颜色编码方式。
输出格式：选择期望的输出文件格式。
输出文件名：为生成的文件指定一个名称。

生成命令和开始转换：设置完参数后，您可以选择"仅生成指令"来查看对应的FFmpeg命令，或直接点击"生成指令并开始转换"启动处理过程。

查看进度和结果：转换开始后，您可以通过进度条实时掌握处理进度。完成后，处理后的视频将自动下载到您的设备上。

源码 joisun/ffmpeg-convertor

原文首发自 sunzy.fun。

好用的话，赏个 Star

Next官网动画效果实现

SunZhongyi — Sun, 04 Aug 2024 00:00:00 GMT

一、引言

距离上一次打开 Next 官网已经快一年了，最近听说有了很多特性更新，想着重新看一看，玩一玩，发现官方多了一些有意思的小动画，今天来研究一下。

动画一

动画分析：

起始动画帧：

该动画有 4 x 2 一共8条线，的运动构成，有偏移动画，和透明度变化。

仔细观察， x 轴方向的动画似乎有一个阶梯的延迟，如果对比开始和结束动画帧，可以发现，y 轴方向的中间两条线运动比两侧的运动速度要快。

动画的实现：

用 omed 初始化一个 vinilla 项目：

dm nextjs-official-anicopy success

构建一个基本UI（tailwind + css）：

<section class="ani-1 relative h-[400px] w-[800px] overflow-hidden">
  <!-- x -->
  <div class="x-line top-[10%]"></div>
  <div class="x-line top-[30%]"></div>
  <div class="x-line top-[60%]"></div>
  <!-- 减去line-width是因为 overflow-hidden 会遮住100%偏移的元素 -->
  <div class="x-line top-[calc(100%-var(--line-width))]"></div>

  <!-- y -->
  <div class="y-line left-0"></div>
  <div class="y-line left-[30%]"></div>
  <div class="y-line left-[70%]"></div>
  <div class="y-line left-[calc(100%-var(--line-width))]"></div>
</section>copy success

:root {
  --line-width: 1px;
  --line-gap: 5px;
  --line-color: white;
}

section.ani-1 {
  .x-line {
    position: absolute;
    background: linear-gradient(to right, var(--line-color), var(--line-color) 50%, transparent 0, transparent);
    background-size: var(--line-gap) var(--line-width);
    width: 100%;
    height: var(--line-width);
  }

  .y-line {
    position: absolute;
    background: linear-gradient(180deg, var(--line-color), var(--line-color) 50%, transparent 0, transparent);
    background-size: var(--line-width) var(--line-gap);
    width: var(--line-width);
    height: 100%;
  }
}copy success

基本效果如下：

先让 x 轴方向的线动起来：


:root {
    --line-width: 1px;
    --line-gap: 5px;
    --line-color: white;
+    /* 定义延迟变量 */
+    --delay: 0.1s;
+    /* 定义动画时长 */
+    --duration: 0.3s;
  }

  section.ani-1 {
    .x-line {
      position: absolute;
      background: linear-gradient(
        to right,
        var(--line-color),
        var(--line-color) 50%,
        transparent 0,
        transparent
      );
      background-size: var(--line-gap) var(--line-width);
      width: 100%;
      height: var(--line-width);
+      animation: var(--duration) offset-x infinite;
+      /* 设定初始位置 */
+      left: -100%;
+    }
+    /* 从第二个元素开始累加延时 */
+    .x-line:nth-child(2) {
+      animation-delay: calc(var(--delay) + 0.2s);
+    }
+    .x-line:nth-child(3) {
+      animation-delay: calc(var(--delay) + 0.4s);
+    }
+    .x-line:nth-child(4) {
+      animation-delay: calc(var(--delay) + 0.6s);
+    }
+  @keyframes offset-x {
+    from {
+      left: -100%;
+    }
+    to {
+      left: 0;
+    }
+  }
copy success

让y 轴方向的线动起来：

  .y-line {
    position: absolute;
    background: linear-gradient(
      180deg,
      var(--line-color),
      var(--line-color) 50%,
      transparent 0,
      transparent
    );
    background-size: var(--line-width) var(--line-gap);
    width: var(--line-width);
    height: 100%;
+    animation: var(--duration) offset-y infinite;
+    /* 设定初始位置 */
+    top: -100%;
+  }
+
+  /* 从第y向中间两条线运动更快，但是有延迟 */
+  .y-line:nth-child(6) {
+    animation-delay: calc(var(--delay) + 0.2s);
+    animation-duration: calc(var(--duration) - 0.5s);
+  }
+  .y-line:nth-child(7) {
+    animation-delay: calc(var(--delay) + 0.2s);
+    animation-duration: calc(var(--duration) - 0.5s);
+  }

+ @keyframes offset-y {
+     from {
+       top: -100%;
+     }
+     to {
+       top: 0;
+     }
+   }
+
copy success

同时开启，添加透明度过渡动画，动画模式修改为 forwards：

.x-line {
-  animation: var(--duration) offset-x infinite;
+  animation: var(--duration) offset-x forwards;
}
.y-line{
-   animation: var(--duration) offset-y infinite;
+   animation: var(--duration) offset-y forwards;
}

@keyframes offset-x {
  from {
    left: -100%;
+    opacity: 1;
  }
  to {
    left: 0;
+    opacity: 0.2;
  }
}

@keyframes offset-y {
  from {
    top: -100%;
+    opacity: 1;
  }
  to {
    top: 0;
+    opacity: 0.2;
  }
}copy success

动画二

动画分析：

页面在滚动到视图区域后，动画执行一次，而后再次进入视图不再触发，除非页面刷新。

具体的动画，动画本身比较简单，三个卡片延迟斜向动画。

如何实现页面到视口区域后仅触发一次动画？

可以借助 Intersection Observer API + animationPlayState 来实现。

动画的实现：

先实现一下基本 UI 布局：

<h2 class="text-white text-2xl">Animation 2</h2>
<section class="ani2 relative h-[400px] w-[800px] overflow-hidden text-white">
  <div class="card1 absolute rounded-xl border border-gray-500 w-[500px] h-[250px] overflow-hidden">
    <div class="header bg-[#1a1a1a] flex h-12">
      <div class="flex-1"></div>
      <div class="border-l border-gray-500 flex justify-center items-center text-xl px-4">atque</div>
    </div>
    <div class="main border border-t border-gray-500 bg-gray-950 h-[calc(100%-3rem)]"></div>
  </div>
  <div class="card2 absolute rounded-xl border border-gray-500 w-[400px] h-[200px] overflow-hidden">
    <div class="header bg-[#1a1a1a] flex h-12">
      <div class="flex-1"></div>
      <div class="border-l border-gray-500 flex justify-center items-center text-xl px-4">nam</div>
    </div>
    <div class="main border border-t border-gray-500 bg-gray-950 h-[calc(100%-3rem)]"></div>
  </div>
  <div class="card3 absolute rounded-xl border border-gray-500 w-[300px] h-[150px] overflow-hidden">
    <div class="header bg-[#1a1a1a] flex h-12">
      <div class="flex-1"></div>
      <div class="border-l border-gray-500 flex justify-center items-center text-xl px-4">tempore</div>
    </div>
    <div class="main border border-t border-gray-500 bg-gray-950 h-[calc(100%-3rem)]"></div>
  </div>
</section>copy success

开启动画：

section.ani2 {
  --duration: 2s;
  --delay: 0.1s;
  .card1,
  .card2,
  .card3 {
    animation: var(--duration) move-tr infinite;
    opacity: 0;
  }
  .card1 {
    left: 300px;
    bottom: 100px;
    z-index: 1;
  }
  .card2 {
    left: 220px;
    bottom: 50px;
    z-index: 2;
    animation-delay: calc(var(--delay) + 0.5s);
  }
  .card3 {
    left: 120px;
    bottom: 0px;
    z-index: 3;
    animation-delay: calc(var(--delay) + 1s);
  }
}

@keyframes move-tr {
  from {
    transform: translateX(-100px) translateY(100px);
    opacity: 0;
  }
  to {
    transform: translateX(0px) translateY(0px);
    opacity: 1;
  }
}copy success

实现元素与视口交叉后开启动画：

首先给动画加一个控制开关, 通过css 变量控制动画启停

section.ani2 {
  --duration: 2s;
  --delay: 0.1s;
  .card1,
  .card2,
  .card3 {
-    animation: var(--duration) move-tr infinite;
+    animation: var(--duration) move-tr forwards;
+    animation-play-state: var(--play-state);
    opacity: 0;
  }
copy success

给 html 中加一个默认的 css 变量：

- <  class="ani2 relative h-[400px] w-[800px] overflow-hidden text-white">
+ <section style="--play-state:paused" class="ani2 relative h-[400px] w-[800px] overflow-hidden text-white">
copy success

通过 Intersection Observer API 检测元素与视口交叉，开启动画：

// ani2
const options = {
    threshold: 0.2// 元素交叉20%时触发

}
const target = document.querySelector(".ani2") as HTMLDivElement
const callback: IntersectionObserverCallback = function (entries) {
    // 元素交叉时，开启动画
    if (entries[0].isIntersecting) {
        target && (target.style.setProperty('--play-state', 'running'))
    }
}
const observer = new IntersectionObserver(callback, options)
target && observer.observe(target)copy success

动画三

动画分析：

看起来像是一个随机点亮的星光闪烁效果，当点亮时，有一个微亮到闪耀的动画。

鼠标hover 之后，可以看到时点亮了一个 NEXT 文字路径，所以其实并不是在所有点位随机点亮，而是只是路径上的点会亮。

观察dom，发现

这些点位有三个状态 "off" | "medium" | "high"
闪烁效果通过伪元素实现的。
一共有90个点位，并通过自定义属性 data-index 记录
固定路径点位上会亮的是固定的部分点位
并不是每次点亮的时候一定会闪烁(通过 scale 实现)

动画的实现：

首先单独尝试实现单独的三个状态：

<section class="ani-3 relative h-[400px] w-[800px] overflow-hidden">
  <div data-light data-state="off" class="spark"></div>
  <div data-light data-state="medium" class="spark"></div>
  <div data-light data-state="high" class="spark"></div>
</section>copy success

section.ani-3 {
  .spark[data-light] {
    /* 三种状态的样式颜色 */
    --light: #3291ff;
    --lighter: #d3e5ff;
    --default: #fff;
    width: 1px;
    height: 1px;
    background-color: var(--default);
    margin: 10px;
    position: relative;
    border-radius: 9999px;
  }
  /* 设置伪元素 */
  .spark[data-light]:before,
  .spark[data-light]:after {
    content: '';
    position: absolute;
    inset: 0;
    opacity: 0;
    width: inherit;
    height: inherit;
    border-radius: inherit;
    transition: opacity 0.5s ease;
  }

  /* 伪元素样式 */
  .spark[data-light]:after {
    background: var(--default);
    box-shadow:
      0 0 1px 1px rgba(50, 145, 255, 0.8),
      0 0 2px 1px rgba(50, 145, 255, 0.25);
  }

  .spark[data-light]:before {
    background: var(--light);
    box-shadow: 0 0 2px 1px rgba(50, 145, 255, 0.25);
  }

  /* medium | high 的样式 */
  .spark[data-state='medium']:before,
  .spark[data-state='high']:after {
    opacity: 1;
  }
  .spark[data-state='off'] {
    background-color: var(--default);
  }
}copy success

接下来，我们需要做到的是，先随机点亮路径上的点，然后随机让它闪烁，值得注意的是，从观察上看，只有点位状态的 data-state=high 的时候，才有可能会闪烁。我们接下来一步步实现。

先创建 90 个点位，我们选择使用 js 来创建。

const template = document.getElementById('spark') as HTMLTemplateElement
const section3 = document.querySelector('.ani-3')
for (let i = 0; i < 90; i++) {
    const $newSpark = template && template.content.firstElementChild?.cloneNode(true) as Element
    $newSpark.setAttribute('data-index', i.toString())
    section3?.appendChild($newSpark)
}copy success

<section class="ani-3 grid grid-cols-[repeat(18,minmax(0,1fr))] relative w-[400px] overflow-hidden">
  <template id="spark">
    <div data-light data-state="off" class="spark"></div>
  </template>
</section>copy success

我们先尝试点亮所有 Next 文本路径的点位，debug 找出所有列表索引：

const template = document.getElementById('spark') as HTMLTemplateElement
const section3 = document.querySelector('.ani-3')
for (let i = 0; i < 90; i++) {
    const $newSpark = template && template.content.firstElementChild?.cloneNode(true) as Element
    $newSpark.setAttribute('data-index', i.toString())
    section3?.appendChild($newSpark)
}
+ const next_path = [72, 54, 36, 18, 0, 19, 38, 57, 76, 58, 40, 22, 4, 6, 24, 42, 60, 78, 7, 79, 8, 80, 43, 44, 82, 65, 48, 31, 14, 10, 29, 67, 86, 88, 70, 52, 34, 16, 15, 17]
+ next_path.forEach((p, ind) => {
+     if (!section3) return
+     let i = section3.querySelector(`[data-index="${String(p)}"]`);
+     i?.setAttribute('data-state', 'high')
+     i && (i.style.transform = 'scale(2.4)')
+     // spark.setAttribute
+ })
copy success

完善逻辑，随机点亮


const template = document.getElementById('spark') as HTMLTemplateElement
const section3 = document.querySelector('.ani-3')
for (let i = 0; i < 90; i++) {
    const $newSpark = template && template.content.firstElementChild?.cloneNode(true) as Element
    $newSpark.setAttribute('data-index', i.toString())
    section3?.appendChild($newSpark)
}
const next_path = [72, 54, 36, 18, 0, 19, 38, 57, 76, 58, 40, 22, 4, 6, 24, 42, 60, 78, 7, 79, 8, 80, 43, 44, 82, 65, 48, 31, 14, 10, 29, 67, 86, 88, 70, 52, 34, 16, 15, 17]

+ const duration = 1000
+ let timerSparking: undefined | number
+
+
+ function setOff(el: HTMLDivElement, delay: number) {
+     if (!el) return
+
+     let timerOff: undefined | number
+     clearTimeout(timerOff)
+     timerOff = setTimeout(() => {
+         el.setAttribute('data-state', 'off')
+         el.style.transform = 'unset'
+     }, delay)
+ }
+ function sparking() {
+     next_path.forEach((p) => {
+         if (!section3) return
+         let i = section3.querySelector(`[data-index="${String(p)}"]`) as HTMLDivElement
+         // 如果 date-state 不是 off 则说明上一轮的处理还没有完成
+         if (i.getAttribute('data-state') === 'off') {
+             // 随机设定不同状态 off / medium
+             const random = Math.random()
+             const type = random > .5 ? 'medium' : 'off'
+
+             // init
+             i.style.transform = 'unset'
+             // set type
+             i.setAttribute('data-state', type)
+
+             // 为 medium 的点位才有可能 high
+             if (type === 'medium') {
+                 // 随机闪烁
+                 if (Math.random() > .7) {
+                     setTimeout(() => {
+                         i.setAttribute('data-state', 'high')
+                         i.style.transform = 'scale(2.4)'
+                         // 持续闪烁 至少400ms
+                         setOff(i, Math.random() * duration + 400)
+                     }, Math.random() * duration)
+                     // 持续随机时长的 medium 状态后闪烁
+
+                 } else {
+                     // 持续随机时长的 medium 状态
+                     setOff(i, Math.random() * duration)
+                 }
+             }
+         }
+
+
+     })
+     // 循环执行
+     clearTimeout(timerSparking)
+     timerSparking = setTimeout(() => {
+         sparking()
+     }, duration)
+ }
+ sparking()
copy success

实现hover时，鼠标全部点亮

function highAll() {
    if (!section3) return;
    enableSparking = false
    next_path.forEach((p, ind) => {
        let i = section3.querySelector(`[data-index="${String(p)}"]`) as HTMLDivElement
        setTimeout(() => {
            i.setAttribute('data-state', 'high')
            i.style.transform = "scale(2.4)"
        }, 10 * ind)
    })

}
function offAll() {
    if (!section3) return;
    enableSparking = false
    next_path.forEach((p, ind) => {
        let i = section3.querySelector(`[data-index="${String(p)}"]`) as HTMLDivElement
        setTimeout(() => {
            i.setAttribute('data-state', 'off')
            i.style.transform = "unset"
        }, 10 * ind)
    })
    enableSparking = true;
    sparking()

}
section3?.addEventListener("mouseenter", highAll)
section3?.addEventListener("mouseout", offAll)copy success

动画四

动画分析：

这是一个 SVG 路径动画，它的大致实现如下：

每一个路径分为一个组，该组中两条 path，重叠

上面的路径通过背景的动态改变，来实现动画效果：

动画的实现：

该动画效果的实现需要通过设计工具画大量线稿，太麻烦了，这里只做一个示例效果，重点在于其实现原理的理解。

在 boxy-svg 或者 svg-path-editor 随便画个路径, 调整 stroke 和大小颜色

复制一层叠加：

<section class="ani-4">
  <svg id="mySvg" style="width: 400px; height: 400px" viewBox="0 0 500 500" xmlns="http://www.w3.org/2000/svg">
    <defs>
      <linearGradient
        gradientUnits="userSpaceOnUse"
        id="gradient-0"
        x1="746.3240441607777"
        y1="250.00944750441704"
        x2="767.7458673719084"
        y2="384.3032596510602"
      >
        <stop stop-color="#FF7432" stop-opacity="0"></stop>
        <stop offset="0.0531089" stop-color="#FF7432"></stop>
        <stop offset="0.415114" stop-color="#F7CC4B"></stop>
        <stop offset="1" stop-color="#F7CC4B" stop-opacity="0"></stop>
      </linearGradient>
    </defs>
    <path
      d="M 410.001 116.667 L 490 116.667 L 490 276.668 L 276.666 276.668 L 276.666 383.333 L 89.999 383.333 L 89.999 196.666 L 10 196.666 L 10 116.667"
      fill="none"
      style="stroke: rgb(0, 0, 0); stroke-width: 4px; stroke-opacity: 0.6"
    ></path>
    <path
      d="M 410.001 116.667 L 490 116.667 L 490 276.668 L 276.666 276.668 L 276.666 383.333 L 89.999 383.333 L 89.999 196.666 L 10 196.666 L 10 116.667"
      fill="none"
      style="stroke-width: 4px; stroke-opacity: 0.6; stroke: url(#gradient-0)"
    ></path>
  </svg>
</section>copy success

const svg = document.getElementById('mySvg')
const gradient = document.getElementById('gradient-0')

function animate() {
  if (!gradient)
    return
  const time = Date.now() * 0.001 // 当前时间（秒）

  // 调整这些值来改变光脉的长度和移动速度
  const speed = 0.9 // 控制移动速度
  const length = 0.2 // 控制光脉长度，值越小，光脉越短

  const x1 = (Math.sin(time * speed) * 0.5 + 0.5) * 100
  const y1 = (Math.cos(time * speed) * 0.5 + 0.5) * 100
  const x2 = (Math.sin(time * speed + length) * 0.5 + 0.5) * 100
  const y2 = (Math.cos(time * speed + length) * 0.5 + 0.5) * 100

  gradient.setAttribute('x1', `${x1}%`)
  gradient.setAttribute('y1', `${y1}%`)
  gradient.setAttribute('x2', `${x2}%`)
  gradient.setAttribute('y2', `${y2}%`)

  requestAnimationFrame(animate)
}
animate()copy success

全部示例见 link, 示例源码见 link.

Volta tips

SunZhongyi — Mon, 12 Aug 2024 00:00:00 GMT

解决 Vscode 中 NPM SCRIPTS panel 点击执行时，使用的环境为全局默认的 terminal 环境的问题

未解决 https://stackoverflow.com/questions/44700432/visual-studio-code-to-use-node-version-specified-by-nvm?rq=2

待更新....

Volta For Windows Setup:

# installation with powershell
winget install Volta.Voltacopy success

create %LOCALAPPDATA%\Volta\hooks.json, set some mirrors

{
  "node": {
    "index": {
      "prefix": "https://npmmirror.com/mirrors/node/"
    },
    "distro": {
      "template": "https://npmmirror.com/mirrors/node/v{{version}}/{{filename}}"
    }
  },
  "npm": {
    "index": {
      "prefix": "https://registry.npmmirror.com/"
    },
    "distro": {
      "template": "https://registry.npmmirror.com/npm/-/{{filename}}"
    }
  },
  "pnpm": {
    "index": {
      "prefix": "https://registry.npmmirror.com/"
    },
    "distro": {
      "template": "https://registry.npmmirror.com/pnpm/-/{{filename}}"
    }
  }
}copy success

done.

为Microsoft Todo开发一个Markdown支持油猴插件

SunZhongyi — Fri, 30 Aug 2024 00:00:00 GMT

一、引言

我是 Microsoft ToDo 的重度依赖用户，基本上是把它当作一个笔记应用来使用的，收集收集面试题啊，或者零碎的知识点之类的。不过它有一点很遗憾，那就是不支持 Markdown, 早都有人反应过这个问题，也不知道为什么直径不支持。我觉得很大原因还是产品的定位不同吧。 Todo 应用本身就不需要过于繁杂的文本描述。

为什么不适用 Notion 呢？ Notion 确实很强大，功能也非常丰富。不过也正是它太过于强大，我觉得有点杀鸡用牛刀的感觉。相比之下，我更喜欢轻量，功能专一，有 Microsoft 背景支持下的 Todo。

考虑到我们需要在不修改Microsoft ToDo原始代码的情况下注入新功能，油猴插件成为了一个理想的选择。油猴插件允许我们将自定义JavaScript代码注入到网页中，这为我们提供了极大的灵活性。此外不需要像 Google Extension 一样需要严格的发布审核流程。

那么就来看看怎么实现这个小插件吧。

一、Setup

本次开发我们使用 Vite + vite-plugin-monkey 插件来开发，感谢插件作者

pnpm create monkeycopy success

基本配置：

//...
export default defineConfig({
  plugins: [
    monkey({
      entry: 'src/main.ts',
      userscript: {
        name: 'Microsoft To-Do Markdown Preview Support - mstodo-md-preview',
        author: 'Zhongyi Sun',
        namespace:'https://github.com/joisun',
        description: 'Microsoft To-Do Markdown Preview Support',
        icon: 'https://t2.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&fallback_opts=TYPE,SIZE,URL&url=https://to-do.live.com/&size=64',
        match: ['https://to-do.live.com/*'],
        license: 'MIT',
        version: pack.version,
      },
//...copy success

二、基本思路

我们要做的事情似乎很简单，也很单一，那就是:

不影响现有文本的情况下把内容预览为 Markdown
支持动态的解析用户输入
受限于页面元素大小，我们需要支持用户自定义的切换展示模式
在切换其他 todo item 的时候，我们需要更新预览内容。

对于Markdown解析，我们选择了广受欢迎的markdown-it库。这个库不仅性能优秀，还提供了丰富的扩展选项，使我们未来能够根据需求自由的自定义Markdown的渲染行为。

为了让代码块更加美观，我们还需要代码块的语法高亮，对此，我们选用 highlight.js 来实现。

三、深入代码实现

让我们从代码层面深入了解这个插件是如何工作的。

首先，我们需要设置基础结构：

import hljs from 'highlight.js'
import markdownit from 'markdown-it'
import { behindDebounce } from './debounce'
import { waitForElement } from './getElement'
import 'highlight.js/styles/tokyo-night-dark.min.css'
import './style.css'copy success

这些导入语句不仅引入了核心的markdown-it和highlight.js库，还包括了一些自定义的工具函数。behindDebounce函数用于性能优化，而waitForElement函数则是为了确保我们的代码在正确的DOM元素出现后才执行。

waitForElement函数的实现，我们使用 MutationObserver 来实现，返回一个Promise：

export function waitForElement(selector: string) {
  return new Promise((resolve) => {
    if (document.querySelector(selector)) {
      return resolve(document.querySelector(selector));
    }

    const observer = new MutationObserver(() => {
      if (document.querySelector(selector)) {
        resolve(document.querySelector(selector));
        observer.disconnect();
      }
    });

    observer.observe(document.body, {
      childList: true,
      subtree: true,
    });
  });
}copy success

这个函数利用了Promise和MutationObserver API。它会持续监视DOM的变化，直到指定的元素出现。

为什么不直接在 document.onload 钩子中去获取元素呢？

答案是，获取不到。像Microsoft ToDo这样的单页应用，DOM元素可能不会立即可用，所以我们需要监听元素出现了我们再获取。当然我们也可以用一个循环方法不断去判断。

接下来，我们配置markdown-it解析器：

const md = markdownit({
  html: false,
  xhtmlOut: false,
  breaks: false,
  langPrefix: 'language-',
  linkify: true,
  typographer: true,
  highlight(str, lang) {
    if (lang && hljs.getLanguage(lang)) {
      try {
        return hljs.highlight(str, { language: lang }).value
      }
      catch (__) {}
    }
    return ''
  },
})copy success

这个配置禁用了HTML标签支持以增强安全性，启用了URL自动链接和排版美化功能。特别值得注意的是highlight函数，它集成了highlight.js，为代码块提供语法高亮功能。

为了使插件能够和ToDo的界面无缝集成，我们需要创建一些自定义的UI元素：

const initBtns = () => {
  if (document.getElementById("mstodo:btns")) return;
  const detailNote = document.querySelector(".detailNote") as HTMLDivElement;
  if (!detailNote) return;

  const edit = createBtnWithIcon(
    EDIT_BTN_ID,
    `<svg ...</svg>`
  );
  const view = createBtnWithIcon(
    VIEW_BTN_ID,
    `<svg ...</svg>`
  );
  const btns = document.createElement("div");
  btns.id = "mstodo:btns";
  btns.style.display = "flex";
  btns.style.gap = ".5em";
  btns.style.justifyContent = "flex-end";
  btns.style.padding = "0.5em 1em";

  btns.appendChild(edit);
  btns.appendChild(view);
  detailNote.parentElement &&
    detailNote.parentElement?.insertBefore(btns, detailNote);
  edit.addEventListener("click", () => {
    showEditor();
  });
  view.addEventListener("click", () => {
    isEdit = false;
    hideEditor();
  });
};copy success

这个函数创建了编辑和预览按钮，并将它们插入到ToDo的界面中。通过这些按钮，用户可以在编辑Markdown文本和查看渲染结果之间自由切换。

插件的核心功能是动态渲染Markdown。这部分的实现依赖于MutationObserver API 和点击事件：

const observerHandler = behindDebounce(function () {
  const qlEditor = document.querySelector(".ql-editor") as HTMLDivElement;
  console.log("mstodo:editor existed: ", !!qlEditor);

  const mdViewer =
    document.getElementById("tstodo:mdViewer") ||
    (createContainer(qlEditor) as HTMLDivElement);

  console.log("mstodo:mdviewer existed: ", !!mdViewer);

  initBtns();
  if (!qlEditor) return;
  const mdContent = qlEditor.innerText;
  try {
    console.log("mstodo:parsing....");
    let result = md.render(mdContent);
    mdViewer.innerHTML = result;

    if (!isEdit) hideEditor();
  } catch (err) {
    console.error(err);
  }
}, 100);

const observer = new MutationObserver(observerHandler);
function observe() {
  observer.observe(document.querySelector(".ql-editor")!, {
    characterData: true,
    childList: true,
    subtree: true,
    characterDataOldValue: true
  });
}copy success

这段代码创建了一个MutationObserver，通过开启 characterData 来监听编辑器内容的变化。每当内容发生变化时，它就会触发Markdown的重新渲染。注意到我们使用了behindDebounce函数来包装处理函数，这是为了避免在用户快速输入时触发过于频繁的渲染，从而提高性能。

为了处理用户的直接交互，我们还实现了点击监听：

function clickListen() {
  document.addEventListener("click", function (e) {
    const target = e.target as HTMLButtonElement;
    const parent = document.querySelector('.tasks') || document.querySelector('.grid-body')
    if (target.className === "taskItem-titleWrapper" || parent?.contains(target)) {
      console.log("mstodo: click listener triggered")
      observerHandler();
    }
  });
}copy success

这个函数确保了在用户切换不同的任务项时能够正确更新Markdown渲染。

整个插件的初始化过程如下：

waitForElement('.ql-editor').then(() => {
  observerHandler()
  hideEditor()
  observe()
  clickListen()
})copy success

这里我们用到了前面提到的waitForElement函数，确保在编辑器元素加载完成后才开始初始化插件。

通过这种方式，我们成功地为Microsoft ToDo添加了Markdown支持，而不需要修改ToDo的原始代码。用户现在可以在任务描述中使用Markdown语法，并实时预览渲染效果。

这个小插件展示了油猴插件的强大功能，也体现了前端开发中解决实际问题的创新思路。通过合理利用现代Web API如MutationObserver，结合成熟的开源库如markdown-it和highlight.js，我们能够相对简单地实现复杂的功能。

让我们来看看效果吧：

https://greasyfork.org/zh-CN/scripts/505577-microsoft-to-do-markdown-preview-support-mstodo-md-preview

源码在这里 here

四、More

我之前写过一些小插件工具，也乘这个机会推荐给需要的朋友。

标题显著,标识等级标题: 用于解决有些网站文章太长，或者样式不明显导致分不清楚等级标题
github-dark-optimization: Github 暗色模式样式优化
gnmdcsdn : CSDN 超极简模式，懂得都懂

还有一些就不过多展开了，有兴趣可以看这里 here。

mac tips

SunZhongyi — Sun, 15 Sep 2024 00:00:00 GMT

Mac 快捷指南

[toc]

一、终端光标移动

基础快捷键

向左移动光标：Ctrl + B（B 代表 Back）。
向右移动光标：Ctrl + F（F 代表 Forward）。
移动到行首：Ctrl + A（A 代表 Ahead）。
移动到行尾：Ctrl + E（E 代表 End）。

单词级移动

向左移动一个单词：Option + ←（向左箭头）。
向右移动一个单词：Option + →（向右箭头）。

删除操作

删除光标前的字符：Ctrl + H。
删除光标后的字符：Ctrl + D。
删除光标前的单词：Ctrl + W。
删除光标后的单词：Option + D。

二、Finder 在当前目录打开终端

Finder - 显示 - 显示路径栏

然后双击(右键) 指定目录 - 终端打开

三、Command 拖动拖动被遮挡的窗口

假设现在有 B 窗口部分遮挡于 A 窗口之上，按住 Command 键，然后拖动 A 窗口，就可以保持 A 不切换到视口最上层的同时移动窗口了。

四、窗口关闭与最小化

操作	命令	等效操作
关闭当前活动窗口	Command + w	红豆豆，关闭窗口按钮
关闭当前活动窗口且保留到dock右侧最小化	Command + m	黄豆豆，最小化窗口按钮
关闭并退出当前活动程序	Command + q	双击 dock栏应用图标-退出
隐藏当前应用程序的所有窗口	Command + h	顶部菜单栏 - 点击当前应用程序的名称，如 Safari - Hide [应用程序名称]
隐藏除了当前应用程序的所有其他应用窗口	Option + Command + h
在同一个应用不同窗口之前快速切换	Command + `

五、拖动文件复制

默认将一个文件从 a 拖动到 b 目录，是移动操作，如果是想要复制，则按住 option 键拖动。

六、文件剪切

不同于 windows， mac 上没有类似 ctrl + x 的按键。默认

Command + c 复制，到指定目录后，如果 command + v 那就是复制。而如果是 command + option + v 就是移动。

七、Quick look

在 Finder 中，选中一个文件，例如图片，然后按空格键就可以快速预览这个文件。在按一次就会收起预览。
如果选中某个文件后，按住空格不放，那么也会触发预览，松开空格会收起预览。

对于预览图片来说，这是一个非常实用的功能。

八、切换 dock 栏显示/隐藏

option + command + d

实际上是切换智能隐藏 dock 栏开关。

九、快速查看网络信息如 ip

按住 option 键，点按状态栏 wifi 图标。

一、十、音量微调

Command + Option + 音量+/-

二、Finder 文件显示简介快捷键

选中文件后 Command + i

三、唤起 Finder 并文件搜索

option+command + space 空格

四、把应用/文件 pin 到 Finder 的工具栏或者侧边栏

按住 Command 拖动应用/文件到指定位置即可。要移除同样按住 command 拖动到任意空白处即可。

这样就可以拖动指定文件到这个应用打开

五、快速定位到dock栏中的应用在 finder 应用程序中的位置

shift + command + 鼠标点按 dock 栏目标应用图标。

快速删除一些临时安装的应用挺好用的

六、企业微信截图

command + shift + a

LetsEncrypt

SunZhongyi — Fri, 22 Nov 2024 00:00:00 GMT

Certbot 是什么？

Certbot 是一个开源工具，用于自动获取和管理来自 Let's Encrypt 的免费 SSL/TLS 证书。它支持大多数现代 Web 服务器（如 Apache 和 Nginx）以及许多主流操作系统，帮助用户轻松配置 HTTPS。

Certbot 的主要功能包括：

自动获取证书：从 Let's Encrypt 自动申请 SSL/TLS 证书。
自动配置 HTTPS：修改 Web 服务器配置以启用 HTTPS（支持 Apache 和 Nginx）。
自动续期：在证书到期前自动续期，确保服务不中断。

如何使用 Certbot？

1. 安装 Certbot

Certbot 提供多种安装方式，取决于你的操作系统和 Web 服务器。以下是常见安装方法：

Ubuntu/Debian：
```
sudo apt update
sudo apt install certbot python3-certbot-nginxcopy success
```
python3-certbot-nginx 是为 Nginx 用户准备的插件。如果使用 Apache，请安装 python3-certbot-apache。

CentOS/RHEL：

sudo yum install epel-release
sudo yum install certbot python3-certbot-nginxcopy success

其他系统：可以参考 Certbot 官方文档：Certbot Installation Guide.

2. 申请证书

根据使用的 Web 服务器，Certbot 提供不同的命令：

为 Nginx 自动申请和配置证书：
```
sudo certbot --nginxcopy success
```
Certbot 会自动检测 Nginx 配置文件并申请证书，同时更新配置文件以启用 HTTPS。
为 Apache 自动申请和配置证书：
```
sudo certbot --apachecopy success
```
仅申请证书（不修改配置）：
```
sudo certbot certonly --standalonecopy success
```
--standalone 模式适合没有 Web 服务器或需要手动配置的场景。

3. 测试 HTTPS

申请证书后，访问你的域名（如 https://yourdomain.com）以验证 HTTPS 是否正常工作。

4. 自动续期

Let's Encrypt 的证书有效期为 90 天，Certbot 提供自动续期功能：

测试续期是否正常工作：

sudo certbot renew --dry-runcopy success

配置自动续期（大多数系统会自动添加到 cron 或 systemd 中）。如果没有自动化，可以手动添加到 cron：
```
0 0,12 * * * certbot renew --quietcopy success
```

5. 其他常用命令

列出已管理的证书：

sudo certbot certificatescopy success

手动删除证书：
```
sudo certbot deletecopy success
```
查看帮助文档：
```
certbot --helpcopy success
```

总结

Certbot 是一个强大的工具，特别适合需要快速、安全地启用 HTTPS 的开发者。通过 Certbot，用户可以轻松申请、配置和管理 SSL/TLS 证书，大大降低了使用 HTTPS 的门槛。

如何检查是否有自动续期配置

要检查你的系统是否已自动配置 Certbot 的续期，可以根据操作系统使用的计划任务管理工具（cron 或 systemd）进行检查。以下是方法：

1. 检查 systemd 定时任务

Certbot 通常在现代 Linux 系统中使用 systemd 定时任务。

查看 systemd 定时任务是否存在：
```
systemctl list-timers --all | grep certbotcopy success
```
输出中如果有类似 certbot.timer 的项，说明 Certbot 已通过 systemd 自动配置续期。
检查 certbot.timer 的状态：
```
systemctl status certbot.timercopy success
```
如果状态显示为 active 或 enabled，说明定时任务正在运行。

2. 检查 cron 定时任务

在一些系统（如旧版 Ubuntu 或不支持 systemd 的系统）中，Certbot 可能通过 cron 实现续期。

查看 cron 的配置文件： Certbot 的续期任务可能位于以下位置之一：
- /etc/cron.d/certbot
- 用户级别的
```
cron
copy success
```
  配置中，使用以下命令查看：
```
crontab -lcopy success
```
在这些配置文件中，找类似以下的内容：
```
0 */12 * * * certbot renew --quietcopy success
```
如果存在类似的条目，说明 Certbot 的续期已通过 cron 配置。

3. 手动测试续期

无论是否自动配置，可以通过以下命令测试续期功能是否正常工作：

sudo certbot renew --dry-runcopy success

如果输出显示类似 Congratulations, all renewals succeeded!，说明自动续期功能可正常使用。

4. 如果没有自动配置

如果没有发现自动续期配置，可以根据需要手动添加：

为 systemd 添加定时器：

sudo systemctl enable certbot.timer
sudo systemctl start certbot.timercopy success

为 cron 添加定时任务： 编辑 cron 配置文件（如 /etc/crontab 或 /etc/cron.d/certbot）：
```
0 */12 * * * certbot renew --quietcopy success
```

这会每 12 小时检查一次证书是否需要续期。

总结

运行 systemctl list-timers --all | grep certbot 或检查 /etc/cron.d/ 是最简单的方法来验证自动续期配置。测试续期命令 certbot renew --dry-run 可以确保自动续期功能正常工作。

实现一个丐版React

SunZhongyi — Tue, 26 Nov 2024 00:00:00 GMT

一、回顾 + 去 React 化

回顾一些基本的React用法和概念。我们知道，一个最基本的 React 使用，是这样开始的。

const element = <h1 title="foo">Hello</h1>
const container = document.getElementById('root')
ReactDOM.render(element, container)copy success

首先通过 JSX 定义了React元素
然后获取了目标dom元素作为挂载容器
将React 元素挂载渲染到了目标容器

React 利用 Babel 或者 SWC 可以将 JSX 语法转义为 React.createElement 方法的调用。这个方法最终会返回一个对象，也就是虚拟 DOM。为了更加明确的认识到这一点，我们可以创建一个 demo 实例。

使用 Babel 或者 SWC 对 JSX 语法转译

$ mkdir jsx2reactElementDemo; cd jsx2reactElementDemo
jsx2reactElementDemo$ npm init -y
# 将 package.json - type 字段设定为 module esm
jsx2reactElementDemo$ npm pkg set type=module
jsx2reactElementDemo$ pnpm install @babel/core @babel/preset-env @babel/preset-react
jsx2reactElementDemo$ touch index.js app.jsxcopy success

// app.jsx
function Card() {
  return (
    <>
      <div>
        <div>
          <div>The Coldest Sunset</div>
          <p>
            Lorem ipsum dolor sit amet, consectetur adipisicing elit.
            Voluptatibus quia, nulla! Maiores et perferendis eaque,
            exercitationem praesentium nihil.
          </p>
        </div>
        <div>
          <span>
            #photography
          </span>
          <span>
            #travel
          </span>
          <span>
            #winter
          </span>
        </div>
      </div>
    </>
  )
}
export default Cardcopy success

import fs from 'node:fs'
// index.js
import Babel from '@babel/core'
import presetEnv from '@babel/preset-env'
import react from '@babel/preset-react'

const file = fs.readFileSync('./app.jsx', 'utf8')
const result = Babel.transform(file, {
  presets: [
    // [presetEnv, { useBuiltIns: "usage", corejs: 3 }], 这行是转译 ECMA 新语法和 polyfill 新特新，这里可以不使用
    react
  ]
})

fs.writeFileSync('./app.output.js', result.code)copy success

使用 node 执行 index.js 文件: node index.js , 并查看输出文件 app.output.js :

function Card() {
  return /* #__PURE__ */ React.createElement(
    React.Fragment,
    null,
    /* #__PURE__ */ React.createElement(
      'div',
      null,
      /* #__PURE__ */ React.createElement(
        'div',
        null,
        /* #__PURE__ */ React.createElement('div', null, 'The Coldest Sunset'),
        /* #__PURE__ */ React.createElement(
          'p',
          null,
          'Lorem ipsum dolor sit amet, consectetur adipisicing elit. Voluptatibus quia, nulla! Maiores et perferendis eaque, exercitationem praesentium nihil.'
        )
      ),
      /* #__PURE__ */ React.createElement(
        'div',
        null,
        /* #__PURE__ */ React.createElement('span', null, '#photography'),
        /* #__PURE__ */ React.createElement('span', null, '#travel'),
        /* #__PURE__ */ React.createElement('span', null, '#winter')
      )
    )
  )
}
export default Cardcopy success

我们可以看到，JSX 语法都被转译成了 React.createElement 方法执行。

上面这个过程也可以使用 swc 来完成，swc 使用 rust 编写，提供了极快的速度和开箱即用的api。为了了解swc 这个现代工具，我们下面是一个快速的演示。

$ mkdir jsx2reactElementDemoSWC
jsx2reactElementDemoSWC$ npm init -y; npm pkg set type=module;touch index.js app.jsx
jsx2reactElementDemoSWC$pnpm install @swc/corecopy success

// index.js
import swc from '@swc/core'

const result = swc.transformFileSync('./app.jsx', {
  jsc: {
    parser: {
      syntax: 'ecmascript',
      jsx: true,
    },
  },
})
fs.writeFileSync('./app.output.js', result.code)copy success

就这么简单的配置，就可以将 jsx 语法转换为 React.createElement。

现在，我们就可以将：

const element = <h1 title="foo">Hello</h1>
const container = document.getElementById('root')
ReactDOM.render(element, container)copy success

转换成下面的内容了：

const element = React.createElement('h1', { title: 'foo' }, 'Hello')
const container = document.getElementById('root')
ReactDOM.render(element, container)copy success

那么 React.createElement 返回的虚拟DOM 长什么样子呢？让我们直接引入 react 包来一探究竟。

`React.createElement` 返回的是什么？

其实我们之前的基础告诉我们了 React.createElement(元素type，组件props, 以及...子组件) 方法会返回虚拟DOM。那么我们通过一个简单的小demo 具体来看看它究竟长什么样。

$ mkdir resultOfReactCreateElement
resultOfReactCreateElement$ npm init -y; npm pkg set type=module;pnpm install react;
resultOfReactCreateElement$ touch app.output.jscopy success

在我们的 app.output.js 文件中，我们复制我们上面的demo中产出的 app.output.js 文件，然后引入 React, 将输出写入到 ./app.output.json

+ import React from "react";
+ import fs from 'node:fs'
  var Card = function () {
    return /*#__PURE__*/ React.createElement(
      React.Fragment,
      null,
      /*#__PURE__*/ React.createElement(
        "div",
        null,
        /*#__PURE__*/ React.createElement(
          "div",
          null,
          /*#__PURE__*/ React.createElement("div", null, "The Coldest Sunset"),
          /*#__PURE__*/ React.createElement(
            "p",
            null,
            "Lorem ipsum dolor sit amet, consectetur adipisicing elit. Voluptatibus quia, nulla! Maiores et perferendis eaque, exercitationem praesentium nihil."
          )
        ),
        /*#__PURE__*/ React.createElement(
          "div",
          null,
          /*#__PURE__*/ React.createElement("span", null, "#photography"),
          /*#__PURE__*/ React.createElement("span", null, "#travel"),
          /*#__PURE__*/ React.createElement("span", null, "#winter")
        )
      )
    );
  };
  export default Card;
+ fs.writeFileSync('./app.output.json', JSON.stringify(Card()));
copy success

现在看看 app.output.json 文件的内容。

可以看到，最终返回的是一个JSON数据的虚拟 DOM 树。

现在，让我们只关注 type 和 props 字段，然后我们将 React.createElement方法进一步修改：

const element = React.createElement('h1', { title: 'foo' }, 'Hello')
const container = document.getElementById('root')
ReactDOM.render(element, container)copy success

替换 JSX 语法部分为虚拟 dom

我们将第一行，手写修改为 JSON 对象，这样，我们就可以暂时摆脱 React.createElement 这个方法了。

- const element = React.createElement("h1", { title: "foo" }, "Hello");
+ const element = {
+   type: "h1",
+   props: {
+     title: "foo",
+     children: "Hello",
+   },
+ };
  const container = document.getElementById("root");
  ReactDOM.render(element, container);
copy success

还没有完成，我们还是用到了 React.render 方法, 让我们想办法脱离它吧！

替换 React.render 方法

const element = {
  type: 'h1',
  props: {
    title: 'foo',
    children: 'Hello',
  },
}
const container = document.getElementById('root')
// ReactDOM.render(element, container);

render(element, container)
function render(element, container) {
  const node = document.createElement(element.type)
  node.title = element.props.title

  const text = document.createTextNode('')
  text.nodeValue = element.props.children

  node.appendChild(text)
  container.appendChild(node)
}copy success

到这里，我们就完成了 React 基本功能，但是我们脱离了 React。这个过程可以很好的解释 React 的基本工作原理。那么接下来，让我更进一步，开始做一个我们自己的丐版 React。

我们先创建一个新的项目目录：

$ mkdir SimpleReact
SimpleReact$ touch core.jscopy success

二、第一步：`createElement` 函数的实现。

我们观察 React.createElement 方法，可以发现这个函数接受了 type, props, children 参数。并返回一个 JSON 对象。

例如：

React.createElement("div")
// 返回
{
    "type": "div",
    "props": {
        "children": []
    }
}copy success

React.createElement("div", null, "Hello")
// 返回
{
    "type": "div",
    "props": {
        "children": "Hello"
    }
}copy success

React.createElement("div",null,"Hello","world")
// 返回
{
    "type": "div",
    "props": {
        "children": ["Hello","world"]
    }
}copy success

我们可以有如下实现：

// core.js
const SimpleReact = {
  createElement(type, props, ...children) {
    return {
      type,
      props: {
        ...props,
        children,
      }
    }
  }
}

export default SimpleReactcopy success

但是，其实数组children 中除了可以是虚拟 DOM 节点之外，还可以是原始值类型，例如文本，所以，让我们为它们创建一个特殊的类型：TEXT_ELEMENT。

  // core.js
  const SimpleReact = {
    createElement(type, props, ...children) {
      return {
        type,
        props: {
          ...props,
-         children,
+         children: children.map((child) =>
+           typeof child === "object" ? child : SimpleReact.createTextNode(child)
+         ),
        },
      };
    },
+   createTextNode(text) {
+     return {
+       type: "TEXT_ELEMENT",
+       props: {
+         nodeValue: text,
+         children: [],
+       },
+     };
+   },
  };
  export default SimpleReact;
copy success

好了，我们的基本实现 createElement 方法。现在有个问题，我们希望测试它，也就意味着我们需要使用 JSX 语法，同时我们又需要用我们自己的 createElement 方法产生编译结果，就像 SimpleReact.createElement这样。

我们现创建一个测试目录：

SimpleReact$ mkdir test; cd test
SimpleReact$ touch App.jsx compile.js
SimpleReact$ npm init -y; npm pkg set type=module
SimpleReact$ pnpm install @babel/core @babel/preset-reactcopy success

App.jsx

function User() {
  return (
    <div>
      <h1>User</h1>
      <p>user info</p>
    </div>
  )
}copy success

compile.js

import fs from 'node:fs'
// index.js
import Babel from '@babel/core'
import react from '@babel/preset-react'

const file = fs.readFileSync('./App.jsx', 'utf8')
const result = Babel.transform(file, {
  presets: [react],
})

fs.writeFileSync('./output.js', result.code)copy success

在 babel 中很简单，我们可以通过注释的方式，告知 babel 使用我们自己的 createElement 方法进行编译。

App.jsx

+ /** @jsx SimpleReact.createElement */
  const User = () => {
    return (
      <div>
        <h1>User</h1>
        <p>user info</p>
      </div>
    );
  };
copy success

我们测试看看，直接使用 node 执行 compile.js

$ node compile.jscopy success

// output.js
/** @jsx SimpleReact.createElement */
function User() {
  return SimpleReact.createElement('div', null, SimpleReact.createElement('h1', null, 'User'), SimpleReact.createElement('p', null, 'user info'))
}copy success

可以看到，babel 将转译结果中 React.createElement 方法替换为了 SimpleReact.createElement。

如果使用 SWC 来编译，我们需要定义一些配置就行

import fs from 'node:fs'
// compile.js
import swc from '@swc/core'

const result = swc.transformFileSync('./App.jsx', {
  jsc: {
    transform: {
      react: {
        runtime: 'classic',
        pragma: 'SimpleReact.createElement', // 自定义 JSX 转换方法
      },
    },
    parser: {
      syntax: 'ecmascript',
      jsx: true,
    },
  },
})

fs.writeFileSync('./output.js', result.code)copy success

三、第二步：`render` 函数

SimpleReact/core.js

  const SimpleReact = {
    createElement(type, props, ...children) {...},
    createTextNode(text) {...},
+   render(element, container){
+     const dom = document.createElement(element.type);
+     container.appendChild(dom);
+   }
  };
  export default SimpleReact;
copy success

首先，我们需要使用元素类型，创建DOM节点，然后将新节点附加到容器。

但是输入的 element 是一个虚拟 dom 树，所以我们需要对其进行递归遍历, 对所有子节点做这件事情。

  const SimpleReact = {
    createElement(type, props, ...children) {...},
    createTextNode(text) {...},
    render(element, container) {
      const dom = document.createElement(element.type);
+     element.props.children.forEach((child) => {
+       SimpleReact.render(child, dom);
+     });
      container.appendChild(dom);
    },
  };
  export default SimpleReact;
copy success

我们还需要处理文本元素，如果元素类型是 TEXT_ELEMENT 我们就创建一个文本节点而不是常规节点。

  const SimpleReact = {
    createElement(type, props, ...children) {...},
    createTextNode(text) {...},
    render(element, container) {
-     const dom = document.createElement(element.type);
+    const dom =
+       element.type === "TEXT_ELEMENT"
+         ? document.createTextNode("")
+         : document.createElement(element.type);
      element.props.children.forEach((child) => {
        SimpleReact.render(child, dom);
      });
      container.appendChild(dom);
    },
  };
  export default SimpleReact;
copy success

现在，我们还有最后一件事需要做，就是将虚拟dom的 props 分配给节点。

  const SimpleReact = {
    createElement(type, props, ...children) {...},
    createTextNode(text) {...},
    render(element, container) {
      const dom =
        element.type === "TEXT_ELEMENT"
          ? document.createTextNode("")
          : document.createElement(element.type);
+     Object.keys(element.props)
+       .filter((prop) => prop !== "children") // children 不是dom 属性，而是子元素
+       .forEach((prop) => {
+         dom[prop] = element.props[prop];
+       });
      element.props.children.forEach((child) => {
        SimpleReact.render(child, dom);
      });
      container.appendChild(dom);
    },
  };
  export default SimpleReact;
copy success

现在，我们已经完成了一个可以将 JSX 元素渲染到 DOM 的库了。让我们看看 core.js 现在的实现：

// core.js
const SimpleReact = {
  createElement(type, props, ...children) {
    return {
      type,
      props: {
        ...props,
        children: children.map(child =>
          typeof child === 'object' ? child : SimpleReact.createTextNode(child)
        ),
      },
    }
  },
  createTextNode(text) {
    return {
      type: 'TEXT_ELEMENT',
      props: {
        nodeValue: text,
        children: [],
      },
    }
  },
  render(element, container) {
    const dom
      = element.type === 'TEXT_ELEMENT'
        ? document.createTextNode('')
        : document.createElement(element.type)

    Object.keys(element.props)
      .filter(prop => prop !== 'children') // children 不是dom 属性，而是子元素
      .forEach((prop) => {
        dom[prop] = element.props[prop]
      })

    element.props.children.forEach((child) => {
      SimpleReact.render(child, dom)
    })

    container.appendChild(dom)
  },
}

export default SimpleReactcopy success

相当的简单，让我们试一试：

现在的目录结构：

SimpleReact$ tree
.
└── core.jscopy success

SimpleReact$ npm init -y; npm pkg set type=module;
SimpleReact$ pnpm install @swc/core
SimpleReact$ touch App.jsx compilte.js index.html main.jscopy success

现在的目录结构如下：

SimpleReact$ tree -I node_modules
.
├── App.jsx # JSX 语法组件
├── compilte.js # 使用 swc 编译 App.jsx
├── core.js # 我们刚才完成的 SimpleReact
├── index.html # html 文件
├── main.js # 我们即将使用的 入口文件
├── package.json
└── pnpm-lock.yamlcopy success

直接复制我们上面实现的 compilte.js 文件内容：

import fs from 'node:fs'
// compile.js
import swc from '@swc/core'

const result = swc.transformFileSync('./App.jsx', {

  jsc: {
    transform: {
      react: {
        runtime: 'classic',
        pragma: 'SimpleReact.createElement', // 自定义 JSX 转换方法
      },
    },
    parser: {
      syntax: 'ecmascript',
      jsx: true,
    },
  },
})

fs.writeFileSync('./output.js', result.code)copy success

App.jsx

import SimpleReact from '../core.js' // 注意这里需要引入，否则后面文件引入的时候，由于 jsx 被编译成了 SimpleReact.createElement 会导致找不到 SimpleReact 变量的错误

function User() {
  return (
    <div>
      <h1>User</h1>
      <p>user info</p>
    </div>
  )
}

export default Usercopy success

然后编译 App.jsx, 输出 output.js

$ node compile.jscopy success

main.js

import SimpleReact from '../core.js'
import App from './output.js'

const root = document.getElementById('root')
SimpleReact.render(App(), root)copy success

就像我们使用 React 那样使用它。

然后在 index.html 文件中引入 main.js

index.html

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Document</title>
  </head>
  <body>
    <div id="root"></div>
    <script src="main.js" type="module"></script>
  </body>
</html>copy success

浏览器打开看看：

一切正常。

四、第三步：Concurrent 并发模式

现在我们需要对现有的代码进行一些重构，因为有一个问题存在。就是在 render 函数中，我们使用了的是递归遍历

element.props.children.forEach((child) => {
  SimpleReact.render(child, dom)
})copy success

这里存在的问题是，一旦我们开始渲染，那么直到遍历整个虚拟dom树完成，我们是无法终止的，这样一来，如果这个组件是一个超复杂的大型组件，那么递归导致的持续占用主线程，这会导致用户其他的操作，例如点击事件，动画渲染等优先级别比较高的行为执行会被阻塞，从而造成很差的用户体验。

所以，为了解决这个问题，我们需要将渲染任务切分为更小的渲染任务单元，然后当用户有更加高优先级的行为，我们让浏览器在完成当前的小任务单元的时候暂停渲染，去执行更加高优先级别的操作，待操作完成后，接着执行未完成的渲染任务。也就是利用浏览器每一帧的任务空闲，去执行我们的任务单元。

https://w3c.github.io/requestidlecallback/#introduction

我们先关注核心的实现：

let nextUnitOfWork = null

function workLoop(deadline) {
  let shouldYield = false // 是否应该让出
  while (nextUnitOfWork && !shouldYield) {
    nextUnitOfWork = performUnitOfWork(nextUnitOfWork)
    shouldYield = deadline.timeRemaining() < 1
  }
  requestIdleCallback(workLoop)
}

requestIdleCallback(workLoop)

function performUnitOfWork(nextUnitOfWork) {
  // TODO
}copy success

这里，我们设计了大致的逻辑结构。

首先，我们定一个了一个 nextUnitOfWork 它表示了下一个渲染的最小任务单元

我们使用了 requestIdleCallback 来递归执行，你可以把它当作 setTimeout, 只不过不是由我们去触发调用，而是浏览器会在任务空闲的时候去调用它 (注意，React现在并不是用它去执行的，而是使用 scheduler package.) 这里我们就使用它。

requestIdleCallback 函数，会给我们一个 deadline 对象参数，我们可以使用它来确定到下一次浏览器再次调用的时候还有多少剩余时间，因此，我们上面的判断中：

shouldYield = deadline.timeRemaining() < 1copy success

就是如果剩余利用时间小于1，那么就应该让出，不要执行我们的渲染任务了。

有一个核心的函数，我们还没有完全实现 performUnitOfWork, 这个函数的任务是执行任务单元，同时还需要返回下一个任务单元。

五、第四步：Fibers

要想组织我们的工作任务单元，那么我们必须将树形结构的虚拟 dom 先转换为线性结构，才能满足我们的逻辑。也就是 fiber tree。

fiber 树其实也是对 DOM 结构的抽象，所以它也是虚拟dom。

在 performUnitOfWork 函数中，对每一个 fiber, 我们需要做三件事：

将元素添加到 dom
为该元素的子元素创建 fibers
选择下一个任务单元

为了便于找到下一个任务单元，所以我们的fiber 设计上需要链接到第一个子元素，然后兄弟节点，和父节点。

解决Adobe non genuine 弹窗禁用问题

SunZhongyi — Sat, 30 Nov 2024 00:00:00 GMT

一、新建防火墙出入网批处理文件

分别在 Adobe 软件的安装位置，例如：E:\Program Files\Adobe 根目录下，和 Adobe 程序公共目录下：C:\Program Files\Common Files\Adobe 创建两个文件(文件名任意)：

bounded_script.bat

@ setlocal enableextensions
@ cd /d "%~dp0"

for /R %%f in (*.exe) do (
  netsh advfirewall firewall add rule name="Blocked: %%f" dir=out program="%%f" action=block
  netsh advfirewall firewall add rule name="Blocked: %%f" dir=in program="%%f" action=block
)
pausecopy success

unbounded_script.bat

@ setlocal enableextensions
@ cd /d "%~dp0"

for /R %%f in (*.exe) do (
  netsh advfirewall firewall add rule name="Blocked: %%f" dir=out program="%%f" action=allow
  netsh advfirewall firewall add rule name="Blocked: %%f" dir=in program="%%f" action=allow
)
pausecopy success

这两个批处理文件分别会递归的将所有子目录下的 .exe 扩展文件加入出站/入站网络防火墙规则。 bounded_script.bat 是禁用， unbounded_script.bat 是删除配置的规则。

如果你对某些目录没有权限导致无法通过右键创建文件，可以使用超级管理员身份启动 Powershell 创建文件。

# 超级管理员 powershell

New-Item -ItemType File -Path "C:\Program Files\Common Files\Adobe\bounded_script.bat"
New-Item -ItemType File -Path "C:\Program Files\Common Files\Adobe\unbounded_script.bat"

# 注意：这里的 E:\Program Files\Adobe 应该替换为你自己的安装目录
New-Item -ItemType File -Path "E:\Program Files\Adobe\bounded_script.bat"
New-Item -ItemType File -Path "E:\Program Files\Adobe\unbounded_script.bat"copy success

写入文件内容保存后，右键管理员运行 bounded_scritpt.bat 文件。

你可以在防火墙 - 高级设置中验证禁用规则。

Tailwindcss implement undeiline effect with gradient background

SunZhongyi — Mon, 09 Dec 2024 00:00:00 GMT

一、Tailwind 通过bg-gradient 实现 underline 下划线效果

<div class="flex h-screen items-center bg-black p-12 text-3xl font-semibold text-white">
  <!-- 1.should be inline element -->
  <!-- 2.parent should not be flex/grid -->
  <div>
    <p class="inline bg-gradient-to-b from-transparent from-70% via-orange-500 via-[percentage:70%_70%] to-orange-500">
      Lorem ipsum dolor sit amet, consectetur adipisicing elit. Tempore error animi adipisci illo atque dolorum ipsum
      eius tenetur facilis explicabo, ab suscipit accusantium praesentium aut exercitationem ducimus aperiam unde nam.
    </p>
    <div class="my-16"></div>
    <p class="inline bg-gradient-to-b from-transparent from-90% via-pink-500 via-[percentage:90%_90%] to-pink-500">
      Lorem ipsum dolor sit amet, consectetur adipisicing elit. Tempore error animi adipisci illo atque dolorum ipsum
      eius tenetur facilis explicabo, ab suscipit accusantium praesentium aut exercitationem ducimus aperiam unde nam.
    </p>
  </div>
</div>copy success

Ollama Basic Usage

SunZhongyi — Thu, 12 Dec 2024 00:00:00 GMT

使用Langchain重构AI接口集成:案例分享

SunZhongyi — Wed, 05 Feb 2025 00:00:00 GMT

在开发 AI 应用时，我们经常需要集成多个 AI 服务提供商的 API。本文将分享一个实际浏览器扩展开发案例，展示如何使用 Langchain 重构传统的 AI 接口集成方案，使代码更加清晰、可维护且易于扩展。

一、重构前的集成 AI 提供商的逻辑

为了认识到重构的目的，让我们先深入了解重构前的代码架构和实现方式。

1.1 服务类型定义

我定义了一个枚举类型，枚举了服务类型

typings\aiModelAdaptor.ts

export enum AgentsType {
    // UI 展示名 = 代码层面服务的名称
    "XunFeiSpark" = "XunFeiSpark",
    "ChatAnywhere" = "ChatAnywhere",
}copy success

这个枚举的作用不仅是类型定义，还直接影响了 Options 页面的 UI 配置。当添加新的枚举值时，系统会自动在配置页面生成对应的 API key 配置选项：

entrypoints\options\components\ApiKeysConfigComponent.tsx

import { AgentsType, AiAgentApiKeys } from '@/typings/aiModelAdaptor'
// ......
function generateOptions() {
  const agents = Object.values(AgentsType)
  return agents.map((agent, index) => {
    return {
      name: agent,
      id: index
    }
  })
}copy success

AgentsType 枚举值将会被转换为 UI 选项，使用户可以为每个 AI 服务配置对应的 API key：

当你新增了一个枚举值后，这里就会多出一个填写选项可供选择：

  export enum AgentsType {
      "XunFeiSpark" = "XunFeiSpark",
      "ChatAnywhere" = "ChatAnywhere",
      "Kimi" = "Kimi",
+     "OpenAI" = "OpenAI"
  }
copy success

但是这只是 UI 的配置入口，对应的代码逻辑也不可缺少。

1.2 AI服务基类

在重构前的方案中，我们定义了一个基类来统一 AI 服务的实现：

lib\aiModels\index.ts

import { AgentsType } from "@/typings/aiModelAdaptor";
import { API_ERROR_TYPE, RequestFn } from "@/typings/app";
import { APIException } from "@/utils/APIException";
import { log } from "@/utils/app";

// 定义 AI 接口的统一结构
export interface AIModelInterface {
  /**API 的 名字 */
  name?: AgentsType;
  /**API 的 URL 请求地址 */
  apiUrl?: string;
  /**API 所应用的模型列表 */
  modelList: string[];
  chatCompletion(input: string): Promise<string>;
}

export class AiApiBasic implements AIModelInterface {
  name: AgentsType;
  apiUrl: string;
  modelList: string[];
  requestFn: RequestFn;
  constructor(
    name: AgentsType,
    apiUrl: string,
    modelList: string[],
    requestFn: RequestFn
  ) {
    this.modelList = modelList;
    this.name = name;
    this.apiUrl = apiUrl;
    this.requestFn = requestFn;
  }
  // AI 服务应该在自己内部尝试多轮 模型尝试,直到全部失败才抛出错误
  async chatCompletion(input: string): Promise<string> {
    const apiKey = await getAgentApiKey(this.name);
    if (!apiKey) {
      throw new Error(`AI API: ${this.name} 未设置apikey，请在setting中设置`);
    }
    for (const model of this.modelList) {
      try {
        // 依次尝试调用各个服务
        const response = await this.requestFn({
          apikey: apiKey,
          apiUrl: this.apiUrl,
          model: model,
          userMessage: input,
          // maxTokens: await greetingWordsLimit.getValue()
        });
        return Promise.resolve(response);
      } catch (error) {
        if (error instanceof APIException) {
          log(
            `${this.name} API failed for model ${model}: \n ${error.type}: ${error.message}`,
            "error"
          );
        }
        continue; // 尝试下一个model
      }
    }
    // 如果所有模型的请求都失败了,那么就会抛出错误
    throw new APIException(
      `All Model for ${this.name} services failed`,
      API_ERROR_TYPE.APIError
    );
  }
}copy success

这个基类实现了错误重试和模型切换的核心逻辑，所有具体的 AI 服务适配器都继承自这个基类。

1.3 提供商具体服务类

以 Kimi 服务为例，看看具体适配器的实现：

我们需要先创建一个对应的文件 lib\aiModels\kimi.ts

// lib\aiModels\kimi.ts
import { AgentsType } from "@/typings/aiModelAdaptor";
import { AiApiBasic } from ".";
import { RequestFn } from "@/typings/app";

// 定义KIMI api 的请求方法和响应处理
const kimiAPI: RequestFn = function ({ apikey, apiUrl, model, userMessage }) {
    return new Promise((resolve, reject) => {
        const options = {
            method: 'POST',
            headers: {
                'Authorization': `Bearer ${apikey}`, // 替换成你的 API key
                'Content-Type': 'application/json',
                'accept': 'application/json',
            },
            body: JSON.stringify({
                model: model,
                messages: [
                    {
                        role: "user",
                        content: userMessage
                    }
                ],
                temperature: 0.3
            })
        };

        fetch(apiUrl, options)
            .then(response => response.json())  // 处理 JSON 响应
            .then(result => {
                if (result.choices && result.choices[0].message) {
                    resolve(result.choices[0].message.content);  // 返回结果
                } else {
                    reject("接口获取信息错误，请排查：moonshot api");
                }
            })
            .catch(error => reject(error));  // 捕获错误
    });
}

// 通过继承 AiApiBasic 类实现kimiAPIAIService 并导出
export class kimiAPIAIService extends AiApiBasic {
    constructor(modelList: string[]) {
        const apiUrl = 'https://api.moonshot.cn/v1/chat/completions'
        super(AgentsType.Kimi, apiUrl, modelList, kimiAPI)
    }
}copy success

这个实现展示了如何处理特定 AI 服务的 API 调用、响应解析和错误处理。

1.4 服务调度器

旧方案中的服务调度是通过 AiApiAdaptor 类实现的，AiApiAdaptor 是 AI 接口的调度器。这个调度器负责管理多个 AI 服务，实现了服务的初始化、调用和错误处理。

在内部实现上，它暴露了一个 initServices 的方法，并接收一个 AI 服务的实例列表，当被调用时，将会按照用户的配置顺序依次排序 AI 服务对象。它还实现了一个 chat 方法，当它被调用的时候，会依次尝试定义的 AI 服务，如果某个 AI 服务的响应异常，那么会暂时移除该服务并尝试下一个 AI 服务，以确保尽力获取 AI 响应。

具体的实现如下：

lib\aiModels\index.ts

/**
 * AI 接口调度器, 自动化尝试调用各个 AI 服务, 包括所有 AI 接口提供的不同模型
 */
export class AiApiAdaptor {
  private services!: AIModelInterface[];
  private toRemoveServices: AIModelInterface[] = [];
  constructor() {}

  /**
   * Initialize the AI model services to be used in the current session. The input services
   * will be filtered by the agentApiKeys stored in the storage. The agentApiKeys will be
   * mapped to the corresponding AI model services and the services that do not have a
   * corresponding agentApiKey will be filtered out.
   * @param services The AI model services to be used in the current session.
   * @returns A promise that resolves when the services are initialized.
   */
  initServices(services: AIModelInterface[]) {
    return agentsStorage.getValue().then((agentApiKeys) => {
      this.services = agentApiKeys
        .map((agentApi) => {
          return services.find(
            (service) => service.name === agentApi.agentName
          )!;
        })
        .filter((service) => service !== undefined);
    });
  }
  /**
   * 当某个服务请求失败的时候，就在该轮循环中结束的时候，暂时移除，避免每次都重试该失败的 服务
   */
  private removeInvalidServices() {
    for (const service of this.toRemoveServices) {
      const index = this.services.indexOf(service);
      if (index !== -1) {
        this.services.splice(index, 1); // 从数组中删除元素
        log(`暂时移除无效的 API 服务 ${service.name}`, "warn");
      }
    }
  }

  async chat(input: string): Promise<string> {
    if (!this.services) {
      throw new APIException(
        "Services is not prepared! Please initialize the AiApiAdaptor first.",
        API_ERROR_TYPE.APINETEXCEPTION
      );
    }

    for (const service of this.services) {
      try {
        // 依次尝试调用各个服务
        const response = await service.chatCompletion(input);
        this.removeInvalidServices();
        return response;
      } catch (error) {
        if (error instanceof APIException) {
          log(`${error.type}: ${error.message} `, "error");
        }
        // 收集需要移除的 service
        this.toRemoveServices.push(service);
        console.log("error", error);
        continue; // 尝试下一个服务
      }
    }
    throw new APIException("All AI services failed", API_ERROR_TYPE.APIError);
  }
}copy success

1.5 初始化 AI 调度器实例并使用

我们是如何初始化并使用 api 的

entrypoints\sidepanel\components\NewRecord.tsx

import { AiApiAdaptor } from '@/lib/aiModels'
//......
let AI: AiApiAdaptor | null = null
async function initAiApiAdaptor() {
    AI = new AiApiAdaptor()
    await AI.initServices([
      new chatanywhereAIService(['gpt-4o-mini', 'gpt-3.5-turbo', 'gpt-4o', 'gpt-4']),
      new xunfeiSparkAPIAIService(['generalv3']),
    ])
}
//......
// ai 对象的调用
const sendToAi = async (payload: any) => {
	if (!AI) {
    	await initAiApiAdaptor()
	}
	const response = await AI.chat(processedMsg)
}
//......copy success

1.6 集成新的 AI 提供商API

在需要集成新的 AI 提供商的API 的时候，我们需要先新增一个 AgentsType 枚举值：

export enum AgentsType {
    "XunFeiSpark" = "XunFeiSpark",
    "ChatAnywhere" = "ChatAnywhere",
+   "Kimi" = "Kimi"
}copy success

然后通过继承 AI服务基类 实现该 提供商具体服务类, 最后要在初始化 AI 调度器实例 的时候将实例传入初始化列表。

async function initAiApiAdaptor() {
    AI = new AiApiAdaptor()
    await AI.initServices([
      new chatanywhereAIService(['gpt-4o-mini', 'gpt-3.5-turbo', 'gpt-4o', 'gpt-4']),
      new xunfeiSparkAPIAIService(['generalv3']),
+     new kimiAPIAIService(['moonshot-v1-8k']),
    ])
}copy success

二、存在的问题

在开发浏览器扩展的过程中，我们需要集成多个 AI 服务提供商的 API。以上实现采用了传统的适配器模式，虽然能够工作，但存在以下显著问题：

代码重复：每个 AI 服务都需要实现类似的请求逻辑和错误处理
服务切换复杂：当一个服务失败时，切换到备用服务的逻辑较为复杂
扩展性限制：添加新的 AI 服务需要编写大量样板代码，需要扩展的代码逻辑分散，需要改好几个地方
代码不够健硕：代码逻辑不够缜密健壮

正是因为这些原因，所以需要对它进行重构。

三、引入 Langchain 来优化逻辑

LangChain 是一个用于开发 LLM（Large Language Model）应用的开源框架。它提供了一套完整的工具和抽象，使得构建基于 LLM 的应用变得更加简单和规范。选择 LangChain 进行重构有以下几个关键原因：

统一的抽象层
- LangChain 提供了统一的模型接口抽象，无论是 OpenAI、Anthropic 还是其他 AI 提供商的模型，都可以通过相同的接口进行调用
- 这种抽象让我们能够轻松切换不同的模型提供商，而无需修改上层业务逻辑
链式调用支持
- LangChain 的 Chain 概念允许我们将多个操作（如提示词处理、模型调用、结果解析等）组合成一个流程
- 这种链式设计使得代码更加模块化，便于维护和扩展
内置的错误处理
- 提供了统一的错误处理机制
- 支持重试逻辑和错误恢复
强大的工具集成
- 内置了许多常用的工具和功能，如提示词管理、记忆系统等
- 这些工具可以帮助我们更好地构建复杂的 AI 应用

在确定使用 LangChain 作为重构的核心框架后，我们需要设计一个清晰的架构来组织代码。这个新架构主要包含三个核心部分：适配器工厂、LangChain 服务层和服务管理器。让我们逐一深入了解每个部分的实现。

3.1 适配器工厂

首先，我们需要一个统一的方式来创建和管理不同的 AI 模型。适配器工厂模式非常适合这个需求，它能够：

统一模型的创建接口
隔离具体实现细节
方便添加新的模型支持

让我们看看具体实现：

lib\aiModels\adapters\index.ts

import { AgentsType } from '@/typings/aiModelAdaptor';
import { BaseLanguageModel } from "@langchain/core/language_models/base";
import { ChatOpenAI } from "@langchain/openai";

export interface AIModelAdapter {
    createModel(apiKey: string): BaseLanguageModel;
}

class ChatAnywhereAdapter implements AIModelAdapter {
    createModel(apiKey: string): BaseLanguageModel {
        return new ChatOpenAI({
            openAIApiKey: apiKey,
            modelName: "gpt-3.5-turbo",
            temperature: 0.7,
            streaming: false,
            configuration: {
                baseURL: "https://api.chatanywhere.tech/v1"
            }
        });
    }
}

class XunFeiSparkAdapter implements AIModelAdapter {
    createModel(apiKey: string): BaseLanguageModel {
        // 这里需要实现讯飞的具体适配逻辑
        return new ChatOpenAI({
            openAIApiKey: apiKey,
            modelName: "spark",
            temperature: 0.7,
            streaming: false,
            configuration: {
                baseURL: "https://spark-api.xf-yun.com/v1"
            }
        });
    }
}

class KimiAdapter implements AIModelAdapter {
    createModel(apiKey: string): BaseLanguageModel {
        return new ChatOpenAI({
            openAIApiKey: apiKey,
            modelName: "kimi",
            temperature: 0.7,
            streaming: false,
            configuration: {
                baseURL: "https://api.moonshot.cn/v1"
            }
        });
    }
}

// 适配器工厂
export class AIModelAdapterFactory {
    private static adapters: Map<AgentsType, AIModelAdapter> = new Map([
        [AgentsType.ChatAnywhere, new ChatAnywhereAdapter()],
        [AgentsType.XunFeiSpark, new XunFeiSparkAdapter()],
        [AgentsType.Kimi, new KimiAdapter()],
    ]);

    static getAdapter(type: AgentsType): AIModelAdapter {
        const adapter = this.adapters.get(type);
        if (!adapter) {
            throw new Error(`No adapter found for model type: ${type}`);
        }
        return adapter;
    }

    // 用于动态注册新的适配器
    static registerAdapter(type: AgentsType, adapter: AIModelAdapter) {
        this.adapters.set(type, adapter);
    }
}copy success

通过这个工厂模式的实现，我们成功统一了不同 AI 服务的创建过程。但是，仅有模型创建的统一还不够，我们还需要一个服务层来处理实际的 AI 交互逻辑。

3.2 langchainService

服务层用来封装与这些模型的交互逻辑。这一层主要负责：

管理模型的生命周期
处理消息模板
执行实际的 AI 调用

下面是具体的服务层实现：

lib\aiModels\langchainService.ts

import { AgentsType } from '@/typings/aiModelAdaptor';
import { PromptTemplate } from "@langchain/core/prompts";
import { RunnableSequence } from "@langchain/core/runnables";
import { StringOutputParser } from "@langchain/core/output_parsers";
import { BaseLanguageModel } from "@langchain/core/language_models/base";
import { AIModelAdapterFactory } from './adapters';
import { targetLanguage, promptTemplate } from "@/utils/storage";

export class LangchainService {
  private models: Map<AgentsType, BaseLanguageModel>;

  constructor() {
    this.models = new Map();
  }

  async initializeModel(type: AgentsType, apiKey: string) {
    try {
      const adapter = AIModelAdapterFactory.getAdapter(type);
      const model = adapter.createModel(apiKey);
      this.models.set(type, model);
    } catch (error) {
      console.error(`Failed to initialize model ${type}:`, error);
      throw error;
    }
  }

  async explain(type: AgentsType, selection: string): Promise<string> {
    const [language, template] = await Promise.all([
      targetLanguage.getValue(),
      promptTemplate.getValue()
    ]);

    // 每次请求创建新的 PromptTemplate
    const _promptTemplate = PromptTemplate.fromTemplate(template);

    const model = this.models.get(type);
    if (!model) {
      throw new Error(`Model ${type} not initialized`);
    }

    const chain = RunnableSequence.from([
      _promptTemplate,
      model,
      new StringOutputParser(),
    ]);

    try {
      const response = await chain.invoke({
        LANGUAGE: language,
        SELECTION: selection
      });

      return response;
    } catch (error) {
      console.error(`Error in ${type} explanation:`, error);
      throw error;
    }
  }

  isModelAvailable(type: AgentsType): boolean {
    return this.models.has(type);
  }
}

// 创建单例实例
export const langchainService = new LangchainService();copy success

服务层解决了与 AI 模型交互的问题，但我们还需要一个更高层的抽象来协调多个服务之间的关系，这就是为什么我们需要服务管理器。

3.3 AiServiceManager

服务管理器采用单例模式，主要负责：

统一管理所有 AI 服务
处理服务的初始化和释放
实现服务之间的故障转移

这是服务管理器的具体实现：

lib\aiModels\aiServiceManager.ts

import { AgentsType } from '@/typings/aiModelAdaptor';
import { langchainService } from './langchainService';
import { agentsStorage } from '@/utils/storage';

export class AIServiceManager {
  private static instance: AIServiceManager;
  private initialized = false;

  private constructor() {}

  static getInstance(): AIServiceManager {
    if (!AIServiceManager.instance) {
      AIServiceManager.instance = new AIServiceManager();
    }
    return AIServiceManager.instance;
  }

  async initialize() {
    if (this.initialized) return;

    try {
      const agents = await agentsStorage.getValue();
      if (!agents) return;

      for (const agent of agents) {
        await langchainService.initializeModel(
          agent.agentName,
          agent.apiKey
        );
      }

      this.initialized = true;
    } catch (error) {
      console.error('Failed to initialize AI services:', error);
      throw error;
    }
  }

  async getExplanation(selection: string): Promise<string> {
    if (!this.initialized) {
      await this.initialize();
    }

    // 获取所有已配置的模型
    const agents = await agentsStorage.getValue() || [];

    // 按配置顺序尝试不同的模型
    for (const agent of agents) {
      if (langchainService.isModelAvailable(agent.agentName)) {
        try {
          return await langchainService.explain(agent.agentName, selection);
        } catch (error) {
          console.error(`Failed to get explanation from ${agent.agentName}:`, error);
          continue;
        }
      }
    }

    throw new Error('No available AI service');
  }
}

export const aiServiceManager = AIServiceManager.getInstance();copy success

阿里云使用docker配置frp服务

SunZhongyi — Sun, 06 Apr 2025 00:00:00 GMT

一、拉取docker 镜像

但是由于国内从今年 6 月份开始都访问不了docker 官方镜像仓库了。我后来也换过一些三方镜像源，都失效了。这次使用阿里云提供的 acr 个人仓库。

基本的操作就是：

确保你本地网络可以正常拉取snowdreamtech/frps将镜像拉取下来
将本地snowdreamtech/frps 镜像推送到阿里云 ACR 个人镜像仓库
在服务器将镜像从 ACR 拉取下来。

配置ACR 个人镜像仓库

官方参考文档

在容器镜像服务中创建个人仓库，包括命名空间、仓库名称。（代码源用于做构建的，直接选本地仓库即可）这个过程会要求你创建一个镜像仓库密码，后续拉取操作也是需要用到的。

创建完成后就可以看到下面的页面

在本地机器上登录，也就是执行上图中的 docker login xxxxxxxxx

➜  ~ docker login --username=jaycethanks crpi-qx4z2go8rkxn8ryi.cn-hangzhou.personal.cr.aliyuncs.com
Password:
Login Succeededcopy success

拉取 frps 镜像到本地(上面拉取过就不需要了)

➜  ~ docker pull snowdreamtech/frps
Using default tag: latest
latest: Pulling from snowdreamtech/frps
cb8611c9fe51: Pull complete
21961a7217b4: Pull complete
4f4fb700ef54: Pull complete
6a0a203414ba: Pull complete
0f2926ad560e: Pull complete
7f1c3a950dd8: Pull complete
Digest: sha256:1ef9ed77ebc5d03c6c1dd20eec8d03bdf61b98e1ba0eda1e7e4aeffa08bdb610
Status: Downloaded newer image for snowdreamtech/frps:latest
docker.io/snowdreamtech/frps:latest
➜  ~ docker images
REPOSITORY           TAG       IMAGE ID       CREATED       SIZE
snowdreamtech/frps   latest    c17ac1a8dd5b   2 weeks ago   37.8MB
# 复制这里的 c17ac1a8dd5b 镜像idcopy success

特别注意⚠️：由于你是在本地拉取的， docker默认会自动拉取使用你电脑的芯片架构对应的镜像。 Aliyun 服务通常是 amd, 架构。如果你在mac 上拉取。默认会拉取arm j架构。因此，**如果你是mac 用户，需要指定 --platform 参数 **为 amd，即：
docker pull --platform linux/amd64 snowdreamtech/frps

给拉取的镜像打一个 tag

➜  ~ docker tag c17ac1a8dd5b crpi-qx4z2go8rkxn8ryi.cn-hangzhou.personal.cr.aliyuncs.com/joi_personal/joi:frpscopy success

把镜像推送到 ACR

docker push  crpi-qx4z2go8rkxn8ryi.cn-hangzhou.personal.cr.aliyuncs.com/joi_personal/joi:frpscopy success

登录你的服务器，拉取镜像

# 登录 acr
docker login --username=jaycethanks crpi-qx4z2go8rkxn8ryi.cn-hangzhou.personal.cr.aliyuncs.com
# 拉取镜像
docker pull crpi-qx4z2go8rkxn8ryi.cn-hangzhou.personal.cr.aliyuncs.com/joi_personal/joi:frps
frps: Pulling from joi_personal/joi
cb8611c9fe51: Pull complete
21961a7217b4: Pull complete
4f4fb700ef54: Pull complete
6a0a203414ba: Pull complete
0f2926ad560e: Pull complete
7f1c3a950dd8: Pull complete
Digest: sha256:a9517b3ed2287556cf489ee1df7fd098eefeb645d7ef5eca0fe6743fe91a729a
Status: Downloaded newer image for crpi-qx4z2go8rkxn8ryi.cn-hangzhou.personal.cr.aliyuncs.com/joi_personal/joi:frps
crpi-qx4z2go8rkxn8ryi.cn-hangzhou.personal.cr.aliyuncs.com/joi_personal/joi:frps
# 查看镜像
docker images
REPOSITORY                                                                    TAG       IMAGE ID       CREATED        SIZE
crpi-qx4z2go8rkxn8ryi.cn-hangzhou.personal.cr.aliyuncs.com/joi_personal/joi   frps      c17ac1a8dd5b   2 weeks ago    37.8MBcopy success

配置 frps 配置文件

登录你的服务器：

mkdir /opt/frp
vim /opt/frp/frps.toml

# 编辑你需要的内容copy success

#示例

bindPort = 7000  # 服务端监听端口
# 可选：Web 管理界面
webServer.addr = "0.0.0.0"
webServer.port = 7500
webServer.user = "admin"
webServer.password = "admin"
# 可选：认证令牌
# auth.token = "your_secure_token"copy success

运行 frps 容器

# 查看镜像
docker images
REPOSITORY                                                                    TAG        IMAGE ID       CREATED        SIZE
crpi-qx4z2go8rkxn8ryi.cn-hangzhou.personal.cr.aliyuncs.com/joi_personal/joi   frps_amd   c17ac1a8dd5b   2 weeks ago    37.8MB

# 启动 frps
docker run -d   --name frps   --restart always   -v /opt/frp/frps.toml:/etc/frp/frps.toml   --network host   5f8d50fd4536copy success

特别注意⚠️：为什么这里使用的是宿主机网络模式，而不是桥接模式？
当使用桥接模式时，如下：
docker run -d   --name frps   --restart always   -v /opt/frp/frps.toml:/etc/frp/frps.toml   -p 7000:7000   -p 7500:7500  c17ac1a8dd5bcopy success
在 Docker 的默认桥接网络模式下，容器拥有自己独立的网络命名空间。外部网络要访问容器内的服务，必须通过 Docker Host 进行端口映射 (-p host_port:container_port)。这意味着：

bindPort (7000)：frpc 需要连接到容器内的 frps，所以必须映射。

webServer.port (7500)：如果你想从外部访问 Dashboard，也必须映射。

remotePort (例如 5173)：当外部用户访问 http://公网IP:5173 时，流量首先到达 Docker Host 的 5173 端口。为了让这个流量进入容器并被 frps 接收，你也必须在 docker run 时映射这个端口 (-p 5173:5173)。

所以，使用宿主机网络模式，可以很好的解决这个问题。

# 查看容器运行情况
docker ps
CONTAINER ID   IMAGE                         COMMAND                  CREATED         STATUS             PORTS                                                                                  NAMES
a4e323f6fb93   5f8d50fd4536                  "/usr/bin/frps -c /e…"   6 seconds ago   Up 5 seconds       0.0.0.0:7000->7000/tcp, :::7000->7000/tcp, 0.0.0.0:7500->7500/tcp, :::7500->7500/tcp   frpscopy success

运行客户端

在此之前可以测试一下你的服务器 7000 端口服务能否测通。可以利用 telnet 或者 netcat(mac 自带)来测试：

nc -v 47.121.146.12 7000
Connection to 47.121.146.12 port 7000 [tcp/afs3-fileserver] succeeded!

# telnel
telnet x.x.x.x 7000copy success

注意⚠️：如果不通，则很可能是你阿里云的网络安全策略没有放开 7000 TCP/UDP 端口

下载 frp 到本地：

你可以到 frp/releases 手动下载解压，也可以到终端通过命令行下载。我这里打算直接装到系统目录。所以我使用命令行：

# mac
wget https://github.com/fatedier/frp/releases/download/v0.61.2/frp_0.61.2_darwin_arm64.tar.gz

# 如果你是linux 则是
https://github.com/fatedier/frp/releases/download/v0.61.2/frp_0.61.2_linux_amd64.tar.gz
copy success

解压

sudo tar -xzf frp_*_darwin_arm64.tar.gz  # Mac[arm] 客户端
sudo tar -xzf frp_*_linux_amd64.tar.gz #linuxcopy success

配置 frpc.toml 客户端配置文件

sudo vim frpc.tomlcopy success

假设你需要穿透本地 5173 端口web 服务，你可以如下配置：

erverAddr = "47.121.146.12" # 换成你自己的公网ip
serverPort = 7000

[[proxies]]
name = "web"
type = "tcp"
localIP = "127.0.0.1"
localPort = 5173
remotePort = 5173copy success

启动本地服务穿透：

./frpc -c frpc.toml
2025-04-06 14:50:10.791 [I] [sub/root.go:142] start frpc service for config file [frpc.toml]
2025-04-06 14:50:10.791 [I] [client/service.go:295] try to connect to server...
2025-04-06 14:50:10.913 [I] [client/service.go:287] [f482d7ebdb23de02] login to server success, get run id [f482d7ebdb23de02]
2025-04-06 14:50:10.913 [I] [proxy/proxy_manager.go:173] [f482d7ebdb23de02] proxy added: [web]
2025-04-06 14:50:10.950 [I] [client/control.go:168] [f482d7ebdb23de02] [web] start proxy successcopy success

测试访问：

访问 frp dashboard : http://47.121.146.12:7500/ （换成你的ip）

(需要配置阿里云安全组开放 7500 tcp 端口)

访问你的web 服务 ： http://47.121.146.12:5173/

额外的

穿透后端接口服务（以java 为例）

#frpc.toml

# frpc.toml

# [common] 部分保持不变
serverAddr = "47.121.146.12"
serverPort = 7000

# 如果之前有 web 服务的代理，可以保留或注释掉
# [[proxies]]
# name = "web"
# type = "tcp"
# localIP = "127.0.0.1"
# localPort = 5173
# remotePort = 5173

# --- 为 Java 服务添加新的代理 ---
[[proxies]]
name = "java-backend-api"   # 给这个代理起一个唯一的名字，方便识别
type = "tcp"                # 对于大多数 HTTP API 或后端服务，TCP 类型是合适的
localIP = "127.0.0.1"       # frpc 连接 Java 服务时使用的 IP (根据第 1 步确定)
localPort = 8080            # frpc 连接 Java 服务时使用的端口 (Java 服务监听的端口)
remotePort = 8081           # **关键**: 公网访问时使用的端口。copy success

利用MCP让AI高效处理项目多语言支持

SunZhongyi — Sun, 13 Apr 2025 00:00:00 GMT

一、引言

在软件开发中，多语言支持（国际化，i18n）是一个常见但又容易被忽视的技术债务。随着项目的扩展，不规范的语言键（keys）会导致维护成本激增，尤其是当团队需要理解和更新这些杂乱无章的标识符时。本文将分享如何利用 Model Context Protocol (MCP) 技术，结合 AI 的语义理解能力，高效处理项目中的多语言支持规范化工作。

我现在维护的项目中，可能有几百个这种不规范的key:

# en
{
  "4ef3c7": "Current IMSI",
  "26989a": "Usable region",
  "0ced5b": "Total package",
  // 更多类似的 key...
}

# zh
{
  "e1c965": "请选择状态",
  "e5e800": "设备号码",
  "fc9b31": "最近同步时间",
  // 更多类似的 key...
}copy success

这种无意义的哈希值作为键名，维护修改起来异常的痛苦不堪 - 完全不知道它们代表什么，需要在哪里使用，以及如何有效地组织它们。

这可能是 “先这样吧，以后再处理” 所遗留的债务问题吧，也无从考究。
好在现在这个项目只有中英双语，我现在如果要对他们进行修改流程上倒是不会太复杂。

而现在如果要对这些 key 进行规范化，传统上需要完成以下步骤：

找到所有引用特定 key 的页面和组件
根据使用场景命名（如公共键："common.xxx.standardKeyName"，特定键："page.section.dialog.standardKeyName"）
修改对应的语言包文件和所有引用

这样就完成了一次 key 的规范化优化，本身是一件很简单的过程，不过问题在于我们需要对几百个key 都要这样重复的操作。这个工作量就很大了，过程非常耗时，而且很容易出错。

二、AI 直接解决的局限性

我们当然不可能人工去完成这件苦差事，我首先尝试了直接使用 AI 来帮助完成这项工作，但是经过我一番换不同的姿势和角度去和ai battle，我发现了一些绕不过的问题：

AI 需要先索引整个代码库，然后在内存中搜索 key，这个过程会因上下文限制而丢失精度, 或者难以控制 AI 的具体行为，可能胡乱的“优化”其他的代码，无论你怎么重申都无济于事。
批量处理容易导致大量修改错误或命名不当
单个处理效率低下且 token 消耗巨大

三、MCP：突破性的解决方案

Model Context Protocol (MCP) 为我们提供了一条新路径。MCP 允许 AI 模型调用外部工具和服务，而不必依赖于自身的上下文记忆来处理大量代码。

关键思路是：我们只需要 AI 的语义理解能力来生成规范的 key 名称，而代码中的查找和替换操作可以交给更专业的工具来完成。

MCP 真的能够解决我们上述问题吗，为什么？

根据我的实践，是非常可以的。

**MCP（Model Context Protocol，模型上下文协议）**是由Anthropic公司提出的一种标准化协议，旨在解决大模型与外部工具、数据源之间的碎片化接入问题。它通过统一的技术规范，让AI模型能够像“即插即用”一样调用各类工具和服务，大幅降低了开发者的集成成本。

其实，我们很容易找到上述场景所面临的问题。我们为什么不能使用脚本的形式去做批量替换处理呢？为什么？因为我们需要理由ai 的上下文语言理解能力，帮我们生成规范的key, 这是核心。

而 AI 在处理这种大量上下文的任务的时候，需要频繁的定位相关key的引用，然后对他们去逐个修改。这个过程很简单，但是对于AI 来说，目前大部分只能够一个一个去修改。这也是导致为什么实际任务处理中，精度低，效率低，token 消耗大的问题根源。

但是 key 的替换其实是一个很简单的操作。直接 vscode 全局查找，然后批量替换，基本可以解决掉 99% 的需要了。

还有 1% 就是字符串拼接没法处理（还就真被我遇上了 - -）。

我们没法让 vscode 去这样操作。像 rpa 机器人一样帮我们自动点击-输入-替换，尽管可能现在的 agent ai 如同雨后春笋一般涌现，不过大部分还没有成熟应用成本高，或者只是支持了浏览器操作。不过，我们可以通过 MCP 服务，将 AI 生成的规范化 key 作为输入，然后让 MCP 服务去执行程序性的文本替换 old-key-->new-key，这样就能够解决上面提到的问题了。

四、实施方案

具体的，我们需要全局的文本搜索能力，还有全局文本替换能力。

modelcontextprotocol/filesystem 就支持文件系统，不过它支持文本替换，却没有支持文本搜索能力。看了下 #335 似乎没有打算继续更新了。为此，我们需要找一个三方的mcp，我找到了Kurogoma4D/file-search-mcp , 不过搜索效率很低。我让ai 帮忙重写了下，使用和vscode一样的底层技术 ripgrep 重写了核心逻辑 —— joisun/file-find-mcp。

工具准备

AI 编辑器：我尝试不同的方案，windsurf、cline、copilot、cursor，目前看来，cursor 对mcp 的支持是最稳定的，cline也可以。这里，我推荐使用 cursor(grok3-beta 就够用了) 进行后续的操作。

我们需要两个核心 MCP 服务：

文件系统操作：modelcontextprotocol/filesystem
文件搜索功能： joisun/file-find-mcp
这里说一下接入方法：
1. 使用rust 写的。需要预装一下 rust 环境: https://www.rust-lang.org/tools/install
2. 拉取代码仓库到本地，后执行下方命令：
```
# Update dependencies
cargo update
# Release build with optimizations
cargo build --release

## Check for errors, warnings, and lints
# cargo check
# cargo clippy

## Run your tests
# cargo testcopy success
```
1. 准备添加 file-find-mcp :
  
  编译构建完后，我们就可以添加 file-search-mcp 这个serve 了, 构建命令会构建出运行文件，目录应该是 /path/to/file-find-mcp/target/release/file-find-mcp, 例如我本地就是：/Users/joi-com/Desktop/mcp_servers/file-search-mcp/target/release/file-search-mcp

配置文件 cursor mcp_config.json 示例：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/joi-com/Desktop/workspace/projectPath" #注意这里需要指向你项目的根目录
      ],
      "autoApprove": [
        "list_allowed_directories",
        "edit_file"
      ]
    },
    "file-find-mcp": {
      "command": "/Users/joi-com/Desktop/mcp_servers/file-find-mcp/target/release/file-find-mcp", #注意这里需要替换为你自己的 file-find-mcp 构建产物路径
      "autoApprove": [
        "search",
        "search_file"
      ]
    }
  }
}
copy success

数据预处理

其实现在，你就可以让 AI 按照我们上面讨论到的思路进行工作了。不过，我的实践中，我发现如果一次性处理的key 太多，还是可能会造成后面的操作跑偏的问题。所以我建议分批操作，分的越小，ai 执行的准确度越高。同时我们也应该需要不断的review，手动抽查 AI 的变更是否正确。

首先，我们需要提取项目中所有不规范的语言 key：

创建一个包含所有语言 key 的源数据文件（如 instruction.map.js），其实就是语言包，可以是 locale/en.json, 我这里是 ts 文件导出的 js 对象。

数据清洗和提取，使用 Node.js 脚本筛选出不规范的 key：

// src/locales/extract.js
const fs = require('node:fs')
const path = require('node:path')

// 正则表达式匹配 6位16进制的key，同时也匹配可能带后缀的key
const HEX_KEY_REGEX = /'?([0-9a-f]{6}(?:id|ud)?)'?\s*:\s*['"](.+?)['"]/g

// 主函数
function extractHexKeys() {
  const results = {}
  const filePath = path.join(__dirname, 'instruction.map.js')

  try {
    const content = fs.readFileSync(filePath, 'utf-8')
    let match

    while ((match = HEX_KEY_REGEX.exec(content)) !== null) {
      const [, key, value] = match
      results[key] = value
    }

    // 将结果写入JSON文件
    const outputPath = path.join(__dirname, 'hex-keys-output.json')
    fs.writeFileSync(
      outputPath,
      JSON.stringify(results, null, 2),
      'utf-8'
    )

    console.log('提取完成！结果已写入:', outputPath)
    console.log('总共找到', Object.keys(results).length, '个匹配项')

    // 打印结果预览
    console.log('\n结果预览:')
    const previewKeys = Object.keys(results).slice(0, 3)
    for (const key of previewKeys) {
      console.log(`\nKey: ${key}`)
      console.log(`Value: ${results[key]}`)
    }

    // 打印带后缀的key
    console.log('\n带后缀的key:')
    const suffixKeys = Object.keys(results).filter(key => key.length > 6)
    for (const key of suffixKeys) {
      console.log(`${key}: ${results[key]}`)
    }
  }
  catch (error) {
    console.error('处理文件时出错:', error.message)
  }
}

// 执行提取
extractHexKeys()copy success

将提取的 key 分批处理，以适应 AI 的处理能力: 这里你可以选择使用脚本去分割文件，我这里直接手动分批的，50 个key 一个文件。

// instruction1.json
{
  "1a8d5b": "Alarm setting",
  "eaa324": "Alarm value setting (each setting triggers a notification once)",
  "10a52f": "Package amount:",
  "73d6a6": "Payable amount:",
  "93ea1f": "Account balance:"
  // more ......
}copy success

AI 提示词工程

为了让 AI 高效地执行规范化任务，我们需要精心设计提示词, 下面是我的提示词：

作为代码重构助手，请规范化项目多语言key。按以下流程操作：

1.  分析任务：
    - 每次分析10个不规范key
    - 使用 **file-find-mcp file_search mcp工具服务搜索** 每个key的使用位置
      参数：排除 json 文件

2.  命名规则：
    - 根据key在页面或者组件中被引用的位置，分析使用场景和上下文
    - 层级结构：[模块].[子模块].[功能].[描述]
    - 通用字段用'common'前缀
    - 特定模块用模块名作前缀
    - 表格列名包含'columns'层级
      示例：'common.columns.totalPackage'、'cardManage.otaCardList.columns.currentImsi'

3.  执行更新：
    - 使用filesystem mcp服务全局替换旧key为新key

4.  重要注意：
    - 一次只处理一个key
    - 保留原key的注释
    - 更新所有引用位置
    - 每组10个key处理完后暂停，等待"continue"指令再继续
    - 仅使用指定的mcp服务，不自行使用其他工具
    - 若mcp执行失败，立即停止并报告原因
    - 不修改与key规范化无关的代码

5.  验证步骤：
    - 每个key替换后，再次搜索确认旧key已完全替换
    - 每组任务结束后，以markdown block 的形式列出changelog以便我直接复制，格式如下：
      示例：
    1.  **Key: `f76ca2` changed to `cardManage.poolList.selection.minOneIccid`**
    - Updated in `/src/locales/en-US/pages.ts`
      - Old: `f76ca2: 'Please select at least one ICCID'`
      - New: `'cardManage.poolList.selection.minOneIccid': 'Please select at least one ICCID'`
    - Updated in `/src/locales/zh-CN/pages.ts`
      - Old: `f76ca2: '请至少选择一个ICCID'`
      - New: `'cardManage.poolList.selection.minOneIccid': '请至少选择一个ICCID'`
    - Updated references in:
      - `/src/pages/CardManage/CardList/components/ForceActiveModal.tsx`
      - `/src/pages/CardManage/CardList/components/EndPreActiveStatus.tsx`
      
6.  内容输入和范围边界
    - 我已经将 src/locales/en-US/pages.ts 中不规范的 key单独提取到了 @locales/instruction1.json，以便于你处理。
    - 你需要以这份文件为索引列表进行任务处理，但是不要修改这个 json 文件
    - 如果发现只有语言包中有这个 key，但是页面或者组件中没有引用过这个 key, 那么可以在语言包中删除这个 key

7.  重要说明
    - **请使用我指定的 mcp 服务进行文件的搜索和替换工作，严禁使用你自己的工具**
    - 如果 mcp 执行失败，请立即停止并报告原因
    - 请严格遵循上述指令和要求
copy success

五、实施效果展示

效果不错

六、优化策略

在 Cursor 编辑器中开启 "Yolo mode"，避免每次 MCP 调用都需要确认

按模块分批处理
可能用到的指令：
分片切换:

from now on, use the @instruction2.json as the keys index map。 and pause after 10 keys processed
copy success

一次性处理所有的key 不要停止。

from now on ,the input key index map gonna be @instruction3.json ,and this time you need finish all of the keys in the file, no pausing untill finish the job, the approch is the same as before,you should handle the keys one by one .
copy success

从暂停处继续

please go ahead, and deal with all the remain keys.
copy success

七、延伸应用与思考

通过结合 AI 的语义理解能力和 MCP 的工具调用能力，我们成功地解决了项目中的技术债务问题。这种方法的优势在于：

高效：MCP 服务直接在文件系统层面操作，避免了 AI 上下文限制
准确：专业工具的搜索和替换功能确保了高精度
可扩展：方法可应用于各种代码重构和规范化任务
省时省力：大幅减少了手动操作和人为错误

通过这个场景对 MCP 的探索和实践，我们也可以发现，本地 MCP server 很适合用于执行一些程序化的操作。

工作流 dotfile 配置文件同步最佳方案

SunZhongyi — Fri, 11 Jul 2025 00:00:00 GMT

unix 环境下，家目录配置如何同步？比如，我有一些 alias 命令，是我日常的使用习惯，如果我需要在多台设备上使用，我需要复制过来复制过去? 又例如像 zsh 这种程序自定义配置，我希望可以在不同的设备上同步，而不是所有设备去单独配置一份。这篇文章，记录如何利用 Git 去同步配置。

一、Pre-Learning

Bare repositoires(裸仓库) 是什么？

我们可以通过 git init --bare 是创建一个裸仓库（bare repository）, 和我们日常的 git init 不同，裸仓库 没有工作目录。一般来说，裸仓库是一个共享仓库，是 push,pull 操作的对象仓库。但是，我们永远不会直接 commit 到这个仓库，因为它没有工作目录，也就意味着我们不能在该仓库中直接修改文件。可以将 --bare 视为将仓库标记为存储设施的一种方式，而不是开发环境。这意味着在几乎所有的 Git 工作流中，中央仓库是裸仓库，而开发者的本地仓库是非裸仓库。

中央(共享)仓库通常以裸仓库创建，避免使用普通仓库的原因是向一个非空仓库推送分支容易覆盖掉已有的修改。

为什么需要裸仓库

如果向一个有工作目录的仓库推送代码，可能会导致冲突和混乱，因为推送的更改可能与工作目录中的文件不一致。裸仓库避免了这个问题，因为它没有工作目录。

简单来说，裸仓库就是专门用来接收推送和提供拉取的"纯净"Git 仓库。

GitHub、GitLab 等平台上的仓库本质上都是裸仓库

普通仓库`git init` （开发环境）	裸仓库`git init --bare` （存储设施）
就像一个"工作台"	就像一个"仓库"或"图书馆"
包含 `.git` 目录（Git 数据）且有实际的文件可以编辑	只包含 Git 数据，没有工作目录
用于日常开发工作	专门用来存储和管理代码历史
包含工作目录（实际的文件）	不能直接编辑文件，不用于直接开发工作
可以直接编辑文件、提交更改	主要用于作为远程仓库，供其他人推送和拉取

主要用途

作为中央仓库：在团队开发中作为共享的远程仓库
服务器端仓库：部署在服务器上，供多个开发者协作
备份仓库：用于备份代码

示例

# 创建裸仓库
git init --bare my-project.git

# 其他开发者可以克隆这个裸仓库
git clone /path/to/my-project.git

# 或者推送到这个裸仓库
git remote add origin /path/to/my-project.git
git push origin maincopy success

Let's Encrypt + Certbot 完整使用指南

SunZhongyi — Sun, 03 Aug 2025 00:00:00 GMT

一、安装 Certbot

# Ubuntu/Debian
sudo apt update
sudo apt install certbot python3-certbot-nginx

# CentOS 7
sudo yum install epel-release
sudo yum install certbot python3-certbot-nginx

# CentOS 8+/RHEL 8+
sudo dnf install certbot python3-certbot-nginx

# 通用方式（推荐）：Snap 安装
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot

# 验证安装
certbot --versioncopy success

二、申请证书前的准备工作

2.1 确保域名解析正确

dig yourdomain.com
nslookup yourdomain.com
curl ifconfig.me   # 确认解析到当前服务器公网 IPcopy success

2.2 检查防火墙

# Ubuntu/Debian
sudo ufw allow 'Nginx Full'
sudo ufw allow 80
sudo ufw allow 443

# CentOS/RHEL
sudo firewall-cmd --add-service=http --permanent
sudo firewall-cmd --add-service=https --permanent
sudo firewall-cmd --reloadcopy success

2.3 Nginx 基础配置

server {
    listen 80;
    server_name yourdomain.com www.yourdomain.com;
    
    location ^~ /.well-known/acme-challenge/ {
        root /var/www/html;
        allow all;
        try_files $uri =404;
    }
    
    location / {
        root /var/www/html;
        index index.html;
    }
}copy success

sudo ln -s /etc/nginx/sites-available/yourdomain.com /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo mkdir -p /var/www/html && sudo chown -R www-data:www-data /var/www/htmlcopy success

三、申请 SSL 证书

3.1 正式环境申请（推荐）

# 单域名
sudo certbot --nginx -d yourdomain.com

# 多域名
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.comcopy success

3.2 测试申请（避免浪费正式环境额度）

Let's Encrypt 每个域名每周最多 50 次证书签发。如果你在调试 Nginx 或脚本，建议使用测试环境：

sudo certbot --nginx --staging -d yourdomain.comcopy success

验证成功后再去掉 --staging 重新申请正式证书。

3.3 非交互式脚本化申请

sudo certbot --nginx \
    -d yourdomain.com \
    -d www.yourdomain.com \
    --non-interactive \
    --agree-tos \
    --email your@email.com \
    --redirectcopy success

3.4 验证证书

sudo certbot certificates
curl -I https://yourdomain.comcopy success

四、自动续期配置

4.1 检查续期方式

sudo systemctl status certbot.timer
sudo systemctl list-timers | grep certbot
ls -la /etc/cron.d/certbotcopy success

4.2 启用 systemd 定时器

sudo systemctl enable certbot.timer
sudo systemctl start certbot.timer
sudo systemctl list-timers certbot.timercopy success

4.3 测试自动续期

sudo certbot renew --dry-runcopy success

五、证书管理常用命令

sudo certbot certificates
sudo certbot certificates --cert-name yourdomain.com
openssl x509 -in /etc/letsencrypt/live/yourdomain.com/fullchain.pem -text -nooutcopy success

六、故障排除

6.1 常见问题

403 Forbidden
检查验证目录权限：

sudo chown -R www-data:www-data /var/www/html
sudo chmod -R 755 /var/www/html
echo "test" | sudo tee /var/www/html/.well-known/acme-challenge/test
curl http://yourdomain.com/.well-known/acme-challenge/testcopy success

DNS 解析失败

dig yourdomain.com @8.8.8.8
dig yourdomain.com @1.1.1.1copy success

80 端口无法访问

sudo systemctl status nginx
sudo ss -tlnp | grep :80
sudo ufw statuscopy success

6.2 日志查看

sudo tail -f /var/log/letsencrypt/letsencrypt.log
sudo tail -f /var/log/nginx/error.log
sudo journalctl -u certbot.timer -fcopy success

七、附录 A：手动续期

# 续期所有即将到期的证书
sudo certbot renew

# 强制续期特定证书
sudo certbot renew --cert-name yourdomain.com --force-renewal

# 续期后自动重载 Nginx
sudo certbot renew --post-hook "systemctl reload nginx"copy success

微前端架构下的js隔离原理

SunZhongyi — Tue, 19 Aug 2025 00:00:00 GMT

一、沙箱隔离

微前端场景下，我们需要深入理解 JavaScript 隔离，以及 JS 沙箱机制的原理。

1.1 为什么需要 JS 隔离？（问题的根源）

想象一下，你正在搭建一个大型网站（主应用），里面集成了来自不同团队开发的多个功能模块（微应用），比如一个“用户中心”模块和一个“商品评论”模块。

如果在没有隔离的情况下，这两个微应用的代码会同时运行在同一个全局环境（window 对象）下。这会立刻引发一系列灾难性的问题：

全局变量冲突：
- 用户中心定义了 window.user = { id: 1, name: 'Alice' }。
- 商品评论为了方便，也定义了 window.user = 'Bob's review'。
- 结果：后加载的应用会覆盖先加载的应用的全局变量，导致前者功能异常。
全局事件监听冲突：
- 两个微应用都监听了 window.onpopstate 事件来处理浏览器路由变化。
- 结果：同样是后者覆盖前者，导致只有一个应用的路由能正常工作。
定时器冲突：
- 一个应用设置了 window.setInterval，但因为代码逻辑问题没有在卸载时用 clearInterval 清除。
- 结果：当你切换到其他应用时，这个定时器还在后台运行，造成内存泄漏和意外的逻辑执行。
第三方库版本冲突：
- 主应用使用了 Vue 2。
- 某个微应用使用了 Vue 3。
- 结果：两者都依赖全局的 Vue 对象，版本不兼容会导致其中一个或两者都无法运行。

核心问题：所有微应用共享同一个 window 对象，导致命名空间污染和环境状态的不可预测性。

解决方案：为每个微应用创建一个“沙箱”（Sandbox），让它们的代码在这个受控的环境里运行，就像孩子们在各自的沙盘里玩沙子，互不干扰。

1.2 JS 沙箱的核心目标是什么？

JS 沙箱的核心目标是：

隔离：确保微应用在运行时对全局 window 对象的修改（如添加变量、修改属性、设置定时器）被隔离在自己的沙箱内部，不会影响到主应用和其他微应用。
干净的环境：确保微应用在每次进入时都能获得一个“纯净”的、符合其预期的全局环境，而在退出时，它对全局环境造成的所有“污染”都会被清理干净。
通信：在隔离的同时，也需要保留与主应用通信的能力（例如，获取主应用传递的数据）。

1.3 JS 沙箱是如何实现的？（三大主流方案）

实现 JS 沙箱主要有三种技术路线，从简单到复杂，各有优劣。

方案一：快照沙箱 (Snapshot Sandbox)

这是最早期、最简单的实现方式，原理非常直观。

原理：利用“拍照”和“恢复”的思想。
如何工作：
1. 激活 (Activate)：在微应用加载之前，给当前的全局 window 对象拍一张“快照”（Snapshot），即遍历 window 上的所有属性并存入一个对象中。
2. 运行：让微应用正常运行。此时，它可能会修改 window，比如 window.myVar = 123。
3. 失活 (Deactivate)：在微应用卸载时，再次遍历当前的 window 对象，与之前拍的“快照”进行对比（Diff）。
  - 如果某个属性在快照里有，但现在的值变了，就把它恢复成快照里的旧值。
  - 如果某个属性是微应用新增的（快照里没有），就把它删除掉。

代码示意：

class SnapshotSandbox {
    constructor() {
        this.proxy = window;
        this.snapshot = {};
        this.modifyProps = {}; // 记录被修改的属性
    }

    activate() {
        // 1. 拍快照
        this.snapshot = {};
        for (const prop in window) {
            if (window.hasOwnProperty(prop)) {
                this.snapshot[prop] = window[prop];
            }
        }
        // 恢复上次被修改的属性
        Object.keys(this.modifyProps).forEach(prop => {
            window[prop] = this.modifyProps[prop];
        });
    }

    deactivate() {
        // 2. 对比和恢复
        for (const prop in window) {
            if (window.hasOwnProperty(prop)) {
                if (this.snapshot[prop] !== window[prop]) {
                    // 记录修改，并恢复
                    this.modifyProps[prop] = window[prop];
                    window[prop] = this.snapshot[prop];
                }
            }
        }
    }
}copy success

优点：
- 实现简单，兼容性好。
致命缺点：
- 无法同时运行多个微应用实例。因为只有一个全局 window，恢复操作会破坏其他正在运行的微应用的环境。因此，它只适用于“单实例”模式。
- 性能开销大，因为需要遍历和对比整个 window 对象。

方案二：代理沙箱 (Proxy Sandbox) - 【现代主流方案】

为了解决快照沙箱无法支持多实例的问题，业界引入了 ES6 的 Proxy 特性，实现了更强大、更高效的沙箱。这是 qiankun 等现代微前端框架的核心。

原理：创建一个“假的” window 对象（代理对象），把这个假对象作为微应用运行时的全局作用域。所有对全局变量的读写操作都会被这个代理拦截。
如何工作：
1. 创建代理：为每个微应用创建一个独立的 fakeWindow 对象（一个空对象 {}）。然后使用 new Proxy(fakeWindow, handlers) 创建一个代理。
2. 拦截操作 (Handlers)：
  - set(target, prop, value) 拦截：当微应用试图执行 window.myVar = 123 时，Proxy 的 set 陷阱会捕获这个操作。它不会去修改真实的 window，而是将 myVar: 123 设置在 fakeWindow 上。
  - get(target, prop) 拦截：当微应用试图读取 window.location 时，Proxy 的 get 陷阱会捕获这个操作。
    - 它会先检查 fakeWindow 上有没有这个属性。如果有（比如之前设置的 myVar），就返回 fakeWindow 上的值。
    - 如果 fakeWindow 上没有（比如 document、location 等原生全局对象），它就会去真实的 window 对象上读取并返回。

代码示意：

class ProxySandbox {
    constructor() {
        const fakeWindow = {};
        const realWindow = window;

        this.proxy = new Proxy(fakeWindow, {
            // 拦截设置操作
            set(target, prop, value) {
                // 赋值操作只在 fakeWindow 上生效
                target[prop] = value;
                return true;
            },

            // 拦截读取操作
            get(target, prop) {
                // 优先从 fakeWindow 中取值
                if (prop in target) {
                    return target[prop];
                }
                // fakeWindow 中没有，则从真实 window 中取值
                const value = realWindow[prop];
                // 对函数绑定正确的 this 上下文
                if (typeof value === 'function') {
                    return value.bind(realWindow);
                }
                return value;
            }
        });
    }
}

// 使用
const sandbox1 = new ProxySandbox();
const sandbox2 = new ProxySandbox();

// 假设在沙箱1的环境中执行代码
// (function(window){
//   window.myVar = 'App1';
//   console.log(window.myVar); // 输出 'App1'
//   console.log(window.document); // 正常访问真实 document
// })(sandbox1.proxy);

// 假设在沙箱2的环境中执行代码
// (function(window){
//   window.myVar = 'App2';
//   console.log(window.myVar); // 输出 'App2'
// })(sandbox2.proxy);

console.log(window.myVar); // 输出 undefined，真实 window 未被污染copy success

优点：
- 完美支持多实例同时运行，因为每个微应用都有自己独立的 fakeWindow，互不影响。
- 性能比快照沙箱好得多，因为它只在读写操作时才触发拦截，而不是遍历整个 window。
缺点：
- 依赖 ES6 Proxy，对浏览器版本有一定要求（不过现代浏览器都已支持）。

方案三：iframe 沙箱

iframe 是浏览器原生提供的最强大的沙箱。每个 iframe 都有一个完全独立的 window、document 和 history 对象，提供了近乎完美的隔离。

原理：将每个微应用都运行在一个独立的 iframe 中。
优点：
- 隔离性最强：天然的 JS、CSS 隔离，不存在任何冲突风险。
- 实现简单，直接把微应用的 URL 填入 iframe 的 src 即可。
缺点：
- 体验和通信问题：
  - URL 不同步：iframe 的 URL 变化不会反映在浏览器主地址栏上，反之亦然，路由管理复杂。
  - UI 不融合：iframe 内部的弹窗（alert, modal）会被限制在 iframe 区域内，无法覆盖整个页面。页面滚动条也会出现主次之分，体验割裂。
  - 通信复杂：主子应用通信需要依赖 postMessage API，比较繁琐。
- 性能和内存开销大：每个 iframe 都是一个完整的、独立的网页环境，创建和销毁的成本很高。

注：一些新的框架如 wujie 采用了“iframe + Web Component的混合方案，巧妙地利用iframe作为纯粹的 JS 沙箱来运行代码，但把渲染（DOM）操作劫持到主应用的 Web Component 中，从而解决了iframe` 的 UI 体验问题，是一种创新的思路。

总结

特性	快照沙箱 (Snapshot)	代理沙箱 (Proxy)	iframe 沙箱
隔离级别	弱	强	完美
多实例支持	不支持	支持	支持
性能开销	高（遍历对比）	低（按需拦截）	非常高（完整页面）
实现复杂度	简单	中等	简单（但应用体验改造复杂）
适用场景	旧版或单实例场景	现代微前端框架首选	对隔离性要求极高，且能接受体验和性能牺牲的场景

一句话总结：现代微前端框架（如 qiankun）的 JS 隔离，主要依赖 Proxy 沙箱机制。它为每个微应用创建一个代理 window，通过拦截读写操作，将所有修改限制在应用自己的作用域内，同时又能访问到真实的全局对象，从而在实现强隔离的同时，保证了性能和多实例共存的能力。

二、快照沙箱的局限性

2.1 问题分析

我们用 window.document 的例子来分析：

沙箱激活前：
- window.document 指向浏览器提供的原生 document 对象。
- 快照沙箱开始工作，它创建了一个 snapshot 对象。
- 执行 snapshot.document = window.document;。此时，snapshot.document 和 window.document 存储的是同一个内存地址，它们都指向那个唯一的 document 对象。
微应用 A 运行中：
- 微应用 A 执行了代码：window.document.title = 'App A's Title';
- 这个操作修改的是那个唯一 document 对象的 title 属性。
沙箱失活时：
- 沙箱开始恢复环境，它会遍历 window 的属性。
- 当检查到 document 属性时，它会做比较：window.document === snapshot.document。
- 因为两者仍然指向同一个对象，这个比较的结果是 true。
- 快照沙箱会认为 window.document 这个“引用”本身没有被改变，因此它不会做任何恢复操作。
- 结果：document 对象的 title 属性已经被永久性地修改了，这个“污染”泄露到了全局，无法被快照沙箱清理。

结论： 快照沙箱只能处理以下几种情况的隔离：

新增全局变量：window.myVar = 1; -> 卸载时可以 delete window.myVar;。
修改全局变量（值类型）：window.name = 'appA'; -> 卸载时可以恢复 window.name 的旧值。
修改全局变量（引用类型，即整个对象被替换）：window.myConfig = {a: 1}; -> 卸载时可以把 window.myConfig 恢复为之前的对象引用。

它无法处理对已有全局对象内部属性的修改，例如：

document.body.appendChild(...)
location.hash = '... (虽然 location 对象的行为更复杂)
window.onpopstate = () => {} (虽然 onpopstate 经常是整个替换，但如果是 addEventListener 就无法追踪了)

2.2 那为什么快照沙箱还存在？它解决了什么？

既然有这么大的缺陷，为什么它会被设计出来并使用过一段时间呢？

历史局限性：在没有 Proxy 的年代（IE 浏览器），这是用纯 JavaScript 实现隔离的一种简单且兼容性好的尝试。
解决了“最常见”的问题：在很多简单场景下，微应用最常见的污染是定义新的全局变量，比如 window.axios、window.myApp 等。快照沙箱对这类问题是有效的。
单实例模式的妥协：快照沙箱的设计理念是“一次只有一个微应用在运行”。在这种模式下，虽然 document 被修改了，但下一个微应用加载时，它可能又会根据自己的逻辑去修改 document，覆盖掉上一个应用的影响。这是一种非常脆弱的平衡，但勉强能用。

所以，您的理解是完全正确的：快照沙箱是一种“不彻底”的沙箱，它提供的隔离能力非常有限，存在明显的“逃逸”漏洞。

2.3 这个问题如何引出 Proxy 沙箱的优越性

您提出的这个痛点，恰恰是 Proxy 沙箱 要解决的核心问题。我们再来看看 Proxy 是如何应对的：

微应用拿到的不是真实的 window，而是一个 proxy 对象。
当微应用执行 window.document.title = 'App A' 时，实际发生了什么？
1. 代码尝试访问 window.document。
2. Proxy 的 get 陷阱被触发，要获取 document 属性。
3. Proxy 内部的 fakeWindow 上没有 document，于是它会去真实的 window 上获取 document 对象并返回。
4. 然后代码尝试给返回的 document 对象的 title 属性赋值。
5. 注意！ 这一步是直接操作真实的 document 对象，Proxy 默认情况下是无法拦截对 window 子对象属性的修改的！

啊哈，看起来 Proxy 也有同样的问题？

不完全是。现代微前端框架如 qiankun 对 Proxy 沙箱做了进一步增强，以处理 document 等特殊对象。

qiankun 的 ProxySandbox 实际上会做一些“魔改”：

对 document 的特殊处理：当微应用通过代理访问 document 时，qiankun 不会直接返回原生的 document。它会返回一个被代理过的 document 对象，或者通过其他方式（如重写 document.querySelector、document.body.appendChild 等关键方法）来劫持 DOM 操作。
事件监听的劫持：qiankun 会重写 window.addEventListener 和 window.removeEventListener。当微应用调用它们时，qiankun 会记录下这个应用注册了哪些事件。在应用卸载时，它会根据记录自动调用 removeEventListener 来清理事件，防止内存泄漏和逻辑冲突。

总结：

快照沙箱的浅拷贝机制无法隔离对 window 上已有对象内部的修改，是一种非常初级和有缺陷的隔离方案。
这个缺陷正是推动技术向 Proxy 沙箱 演进的关键原因。
即使是基础的 Proxy 沙箱，也需要对 document、addEventListener 等关键全局 API 做额外的劫持和处理，才能实现更彻底的隔离，尤其是在 DOM 和事件层面。这使得现代微前端框架的沙箱实现比简化版模型要复杂得多。

Monaspace字体配置

SunZhongyi — Tue, 23 Sep 2025 00:00:00 GMT

一、📥 下载选择

推荐下载：monaspace-nerdfonts-v1.301.zip（包含编程图标）
替代选择：monaspace-variable-v1.301.zip（文件更小，现代应用）

二、🎯 程序员安装方案

最小安装（推荐）

只需安装每个字型的 Regular 版本：

MonaspaceArgonNF-Regular.otf
MonaspaceKryptonNF-Regular.otf
MonaspaceNeonNF-Regular.otf
MonaspaceRadonNF-Regular.otf
MonaspaceXenonNF-Regular.otf
copy success

完整开发套装

安装常用变体组合：

MonaspaceArgonNF-Regular.otf
MonaspaceArgonNF-Bold.otf  
MonaspaceArgonNF-Italic.otf
MonaspaceArgonNF-BoldItalic.otf
copy success

三、⚙️ 编辑器配置

VS Code

{
  "editor.fontFamily": "'Monaspace Argon', monospace",
  // 下面可选，用于开启字体连字
  "editor.fontLigatures": false,
  "editor.tokenColorCustomizations": {
    "textMateRules": [
      {
        "scope": [
          "comment.line",
          "comment.block",
          "comment.line.double-slash",
          "comment.block.documentation"
        ],
        "settings": {
          "fontFeatures": "'calt', 'liga', 'dlig', 'ss01', 'ss02', 'ss03', 'ss04', 'ss05', 'ss06', 'ss07', 'ss08'"
        }
      }
    ]
  }
}copy success

JetBrains IDE

Settings → Editor → Font → Monaspace Argon
copy success

终端配置

iTerm2/终端.app：Preferences → Profiles → Text → Font → Monaspace Argon

Windows Terminal：

{
  "fontFace": "Monaspace Argon"
}copy success

四、🎨 字型选择指南

Argon：平衡易读（推荐默认）
Krypton：技术感强
Neon：圆润现代
Radon：传统等宽
Xenon：独特个性

五、💡 使用技巧

开启连字：提升代码美观度
可变字体：支持无极字重调节
Nerd Fonts：终端图标显示完整
多字型混合：不同语言使用不同字型

GitHub: https://github.com/githubnext/monaspace

使用whistle转发到本地开发服务

SunZhongyi — Mon, 10 Nov 2025 00:00:00 GMT

一、背景

我们公司的技术架构是微服务模式，采用 node 作为BFF 中间层，类似这样的架构

graph TB
    subgraph "前端层"
        Web[Web 应用]
        Mobile[移动应用]
        Desktop[桌面应用]
    end
    
    subgraph "BFF 层 (Node.js)"
        BFF1[Web BFF]
        BFF2[Mobile BFF]
        BFF3[Desktop BFF]
    end
    
    subgraph "微服务层"
        UserService[用户服务]
        OrderService[订单服务]
        ProductService[商品服务]
        PaymentService[支付服务]
    end
    
    subgraph "数据层"
        DB[(数据库)]
        Cache[(缓存)]
    end
    
    Web --> BFF1
    Mobile --> BFF2
    Desktop --> BFF3
    
    BFF1 --> UserService
    BFF1 --> OrderService
    BFF1 --> ProductService
    
    BFF2 --> UserService
    BFF2 --> OrderService
    BFF2 --> PaymentService
    
    BFF3 --> ProductService
    BFF3 --> UserService
    
    UserService --> DB
    OrderService --> DB
    ProductService --> DB
    PaymentService --> DB
    
    UserService --> Cache
    ProductService --> Cache
    
    style BFF1 fill:#4CAF50
    style BFF2 fill:#4CAF50
    style BFF3 fill:#4CAF50
copy success

此外，为了满足高度自定义开发环境下，多分支协作开发测试的场景，前端通过 cookie 可以动态指定某个前端服务具体要请求到对应服务的哪一个分支, 具体来说，就像这样

example-service-a=http://example-service-a-feature-abc.test.example.com:80; 
example-service-b=http://example-service-b-feature-abc.test.example.com:80; 
example-service-c=http://192.168.31.124:8082/international/
copy success

我们在node BFF 层中去处理转发逻辑，这样就实现了，前端模块 example-service-a 的请求，就会指定转发到 example-service-a-feature-abc 这个服务, 前端模块 example-service-b 的请求，就会指定转发到 example-service-b-feature-abc 这个服务。

你可能注意到了 example-service-c=http://192.168.31.124:8082/international/, 192.168.31.124:8082 不是一个本地ip吗？是的，我们局域网网络也是可以代理转发的。这样就可以实现本地开发，无需发布代码，只要页面刷新，就可以看到本地代码了。像这样

graph LR
    Browser[浏览器] --> BFF[BFF 代理层]
    
    BFF -->|转发| Local[本地开发<br/>192.168.x.x:3000]
    BFF -->|转发| Remote[远程服务<br/>test-api.com]
    
    Local -.->|代码修改<br/>页面刷新| Browser
    
    style Local fill:#FF9800
    style BFF fill:#4CAF50
copy success

但是有一个问题很明显，就是太慢了。

graph LR
    A[浏览器] -->|1| B[远程BFF]
    B -->|2| C[本地服务]
    C -->|3| B
    B -->|4| A
    
    style B fill:#FF5722
    style C fill:#FF9800
    
    D[数据绕了2圈<br/>所以很慢]
    style D fill:#FFF9C4
copy success

实际上，如果文件没有那么大，同时网络条件较好的情况下，其实这也能接受。但是一旦公司网络有上下行限制，或者网络拥堵，加上文件较大，刷新一次页面，等个大几十秒是便饭。

一、Whistle 拦截转发

Whistle, 是一个基于 Node.js 的网络抓包调试工具。支持非常灵活的配置规则。可以配置拦截指定的流量并按照指定规则进行转发。而我们要做的很简单，就是把特定请求拦截并转发到我本地开发服务器就行。

使用Whistle 如果需要支持https 请求处理，需要先安装安全证书 (略)，我们开发服务都是http，可配可不配。

whistle 的使用非常简单，安装GUI版本，打开后，

系统代理

先开启系统代理

如果你同时使用了 clash，记得取消 clash 的系统代理勾选

配置转发规则

test.example.com/international http://127.0.0.1:8081/international

whistle 非常强大，我们还可以修改响应头，为了让我们可以辨别，我们可以加一个自定义响应头，如下

test.example.com/international resHeaders://x-proxy=Whistle http://127.0.0.1:8081/international

验证一下

在响应头看到我们的自定义响应头

二、Whistle + ZeroOmega 实现更加灵活的转发策略

有时候，我们需要更加灵活的方式，例如我希望 clash 接管系统代理，把指定流量交给 whistle 去处理。

ZeroOmega 是frok自 SwitchyOmega 原项目作者不再维护。 ZeroOmega 可以按照特定规则进行流量转发。

看起来都是流量转发？那为什么不直接使用 ZeroOmega 这个插件就好了？原因是因为 ZeroOmega 是基于浏览器的 Proxy API 工作，而浏览器层面的代理协议（HTTP / HTTPS / SOCKS5）定义是这样的：
协议://用户名:密码@主机:端口copy success
并不支持带有路径，而 whistle 是一个本地代理服务器，它暴露了代理服务的端口。

通过这两个工具，我们要实现的是什么呢

ZeroOmage 可以配置不同的情景模式，我们可以借由该特性将指定请求转发到 whistle 我们希望

转发 http://example-service-a.com/intl/ 入口流量，转发到whistle 处理
其他的走默认情景模式 (我是配置了一个 clash请求模式)，也就是其他流量走 clash

Whistle 中需要配置监听规则，监听 http://example-service-a.com/intl/, 然后转发到本地服务

graph TB
    Browser[浏览器 + ZeroOmega]
    
    Browser --> Split{ZeroOmega 分流}
    
    Split -->|目标路径<br/>example.com/matched/path| Whistle[Whistle 本地代理<br/>localhost:8899]
    
    Split -->|其他流量<br/>example.com/not-matched/path| Clash[Clash 系统代理]
    
    Whistle --> Local[本地开发服务<br/>localhost:3000]
    

copy success

三、具体配置

ZeroOmega

首先配置 ZeroOmega，在我的实际场景中，我需要转发这些地址到我本地开发服务器

为了通用性，接下来我们将 test.example.com作为讨论的域名，也就是说，上面的请求可以看作:

http://test.example.com/international/js/chunk-vendors.js
http://test.example.com/international/
http://test.example.com/international/js/app.jscopy success

我建立了两个ZeroOmega请求规则，如下：

Auto switch 配置动态应用规则

正则参考: ^http(|s):\/{2}test\.example\.com\/international*

whistle 配置

先确认我们端口和 ZeroOmega中对应，我用的是8888（默认是8899）

其他的rule配置和之前一样

不过，现在可以取消 whistle 的系统代理了，让clash 去做系统代理

AI 绘图的最佳实践：DaC, MCP 与 Kroki 的终极组合

SunZhongyi — Thu, 20 Nov 2025 00:00:00 GMT

核心观点：在 LLM 时代，绘图不再是拖拽像素，而是Token 的艺术。把“思考”留给 AI，把“排版”留给算法，把“渲染”交给 Kroki。

让 GPT-4 或 Claude 直接画图（生成图片）通常是灾难现场：文字乱码、逻辑错乱。因为 LLM 是概率模型，它懂逻辑，但极其不擅长处理像素坐标 (X,Y)。

最优雅的解法是 Diagram as Code (DaC)。

LLM 生成代码，工具渲染图片。最近我在开发基于 MCP (Model Context Protocol) 的绘图工具链，测试了主流 DaC 方案。本文将从 AI 工程化的角度，聊聊如何搭建一套省 Token、高颜值、易集成的 AI 绘图系统。

一、评测维度：AI 视角的“不可能三角”

区别于人类手写，AI 生成代码主要关注三个指标：

Token 密度 (Token Efficiency)：
- 同样的图，代码越短越好。这不仅省钱，更能防止撑爆 Context Window（上下文窗口）。
算法鲁棒性 (Layout Algorithm)：
- AI 生成的节点顺序往往是乱的。工具必须具备强大的自动布局能力，能把一堆乱序节点排列得井井有条。
模型对齐 (Alignment)：
- LLM 对该语言是否“母语级”掌握？冷门语法会导致严重的幻觉。

二、主流选手深度横评

2.1 Mermaid：LLM 的“通用语”

如果你的 AI Agent 需要最大兼容性，Mermaid 是唯一解。

AI 适配度：👑 Top 1。Github 的海量数据让所有模型都精通它。
Token 消耗：中等。
缺陷：布局算法较弱。节点超过 15 个时，生成的流程图容易变成“蜘蛛网”，难以阅读。
适用场景：轻量级对话、简单的时序图/流程图。

2.2 D2 (Declarative Diagramming)：Token 吝啬鬼

这是我最推荐给 AI 使用的“黑马”语言。

Token 效率：极高。
- Mermaid: A --> B: Text
- D2: A -> B: Text (支持嵌套结构，大幅减少重复声明)
布局天花板：D2 的 TALA 引擎是目前自动布局的最强王者。即便 AI 生成的逻辑很乱，D2 也能渲染出非常现代、美观的拓扑图。
适用场景：复杂系统架构图、ER 图、追求高颜值的输出。

2.3 PlantUML：逻辑重坦

地位：严谨场景（如复杂 UML 类图）的守门员。
缺点：语法啰嗦，Token 消耗大（大量的 start/end, participant 样板代码）。
建议：除非必须遵循严格 UML 标准，否则在 AI 场景下不推荐。

2.4 反面教材：为什么不选 JSON/XML？

Excalidraw/Draw.io：千万别让 AI 生成这些格式。
- Token 爆炸：描述一个矩形需要几十行 JSON 坐标属性。
- 坐标地狱：AI 算不准绝对坐标，会导致严重的元素重叠。

三、渲染架构：Kroki 才是 AI 的最佳伴侣

选好了语言（Mermaid/D2），怎么渲染？

在 AI Agent 或 MCP Server 中安装 Java (PlantUML)、Node.js (Mermaid) 或 Go 二进制 (D2) 是非常愚蠢的架构设计——环境依赖太重，Docker 镜像会巨大无比。

Kroki 是完美的解决方案。

它是一个统一的渲染网关，提供简单的 HTTP API。你只需要把代码丢给它，它返回图片。

3.1 为什么 Kroki 适合 AI？

Unified Interface：Agent 只需要知道一个 URL 格式，就能支持 20+ 种绘图语言。
Stateless：无状态，极其适合 Serverless 或 MCP 部署。
私有化：一行 Docker 命令即可私有部署，数据不出内网。

# 极简部署 Kroki
docker run -d --name kroki -p 8000:8000 yuzutech/krokicopy success

Vue 组件数据流重构实战：从直接修改到完全 Immutable

SunZhongyi — Wed, 17 Dec 2025 00:00:00 GMT

一次关键业务模块的架构优化之旅：如何将 Vue 组件从"能用"升级到"优雅"

一、前言

$$
在开发 Vue 应用时，我们经常会遇到父子组件之间的数据传递问题。虽然 Vue 官方文档明确指出应该遵循"单向数据流"原则，但在实际项目中，为了快速实现功能，我们有时会采用一些"捷径"——比如直接修改父组件传入的引用。

这种做法在小型项目或原型开发阶段看似没有问题，但随着项目规模增长和团队协作深入，它会带来越来越多的问题：数据流不清晰、难以调试、容易产生副作用、违反 Vue 最佳实践等。

本文将分享一次真实的生产环境代码重构经历，展示如何将一个关键业务模块从"直接修改引用"模式优化为"完全 Immutable + 纯函数"架构。

二、背景：一个真实的业务场景

我们的项目是一个 OTA（Over-The-Air）卡套餐管理系统。其中有一个核心功能：网络运营商配置。

业务复杂度

数据规模：50-200 条网络配置记录
编辑模式：支持单行编辑、批量编辑、合并编辑三种模式
特殊规则：全球场景下，只有中国和美国需要应用特殊的切换规则
数据一致性：配置取消后需要清除历史字段，确保表格合并功能正常工作

原始实现的问题

// carrier-config-dialog.vue（子组件）
open(srcData) {
  this.srcData = srcData; // ❌ 直接引用父组件数据
}

handleConfirm() {
  this.$set(this.srcData, index, newValue); // ❌ 直接修改父组件数据
  this.$emit("confirm", result);
}

// networks-viewer-configurator.vue（父组件）
handleCarrierConfigConfirm() {
  this.forceUpdateTable(); // ❌ 需要手动强制刷新
  this.$emit("input", this.networkConfigs);
}copy success

核心问题：

子组件直接修改父组件传入的数据
数据流不清晰，难以追踪变更
需要手动强制刷新视图
违反 Vue 单向数据流原则

三、第一阶段：从直接修改到事件驱动

问题分析

这是一个典型的反模式（Anti-pattern）：

父组件数据 (引用)
    ↓
子组件直接修改
    ↓
父组件数据被动变化
    ↓
需要手动 forceUpdate
copy success

为什么会出现这种问题？

快速实现功能，忽略了架构设计
对 Vue 响应式原理理解不深
缺少代码审查和最佳实践指导

解决方案：引入深拷贝 + 事件驱动

步骤 1：子组件使用数据副本

// ✅ 改进后
open(srcData) {
  // 创建深拷贝，避免直接引用
  this.srcData = JSON.parse(JSON.stringify(srcData));
}copy success

关键改进：

子组件操作的是独立副本
不会意外修改父组件数据
只有在用户确认时才返回数据

步骤 2：返回完整数据数组

// ✅ 改进后
handleConfirm() {
  // ... 在副本上进行修改
  this.$set(this.srcData, index, newValue);
  
  // 返回完整的修改后数据数组
  this.$emit("confirm", this.srcData);
}copy success

关键改进：

明确的数据返回
由父组件决定如何应用数据
遵循"Props down, Events up"原则

步骤 3：父组件接收并应用数据

// ✅ 改进后
handleCarrierConfigConfirm(updatedData) {
  // 更新本地数据
  this.networkConfigs = updatedData;
  
  // Vue 响应式系统自动更新视图
  this.$emit("input", this.networkConfigs);
}copy success

关键改进：

不再需要 forceUpdateTable()
Vue 响应式系统自动处理
数据流清晰可追踪

第一阶段成果

✅ 新的数据流
父组件 networkConfigs (原始数据)
    ↓
子组件 open(srcData) 
    ↓
创建深拷贝 this.srcData
    ↓
修改副本
    ↓
emit('confirm', this.srcData)
    ↓
父组件接收 updatedData
    ↓
更新 this.networkConfigs = updatedData
    ↓
Vue 自动更新视图
copy success

优势：

✅ 符合 Vue 最佳实践
✅ 数据流清晰可追踪
✅ 不需要手动强制刷新
✅ 降低组件间耦合

四、第二阶段：从修改副本到完全 Immutable

进一步思考

虽然第一阶段的改进已经符合 Vue 最佳实践，但仔细审视代码，我们发现还有优化空间：

// 第一阶段的代码
applySingleRowEdit(shouldClear) {
  // ... 计算逻辑
  this.$set(this.srcData, index, newValue); // 修改副本
  // 没有返回值
}

handleConfirm() {
  this.applySingleRowEdit(shouldClear);
  this.$emit("confirm", this.srcData);
}copy success

存在的问题：

apply 方法有副作用（修改 srcData）
依赖 Vue 的 $set API
不是纯函数，难以测试
数据流不够清晰

解决方案：完全 Immutable + 纯函数

核心思想：函数不修改输入，只返回新值

改进 apply 方法：返回新数组

// ✅ 完全 Immutable
applySingleRowEdit(shouldClear) {
  const targetRowIndex = this.srcData.findIndex(
    (it) => `${it.country}-${it.network}` === this.editRowKey
  );
  
  if (targetRowIndex === -1) return this.srcData;
  
  // 使用 map 返回新数组
  return this.srcData.map((row, idx) => {
    if (idx === targetRowIndex) {
      const shouldApplyRuleConfig = 
        !shouldClear && this.preCheckIfApplyConfig(row);
      
      const result = shouldApplyRuleConfig
        ? { ...this.ruleConfigFormData, ...this.formData }
        : { ...this.cloneDefaultRuleConfig(), ...this.formData };
      
      return { ...row, ...result };
    }
    return row;
  });
}copy success

关键改进：

✅ 纯函数：相同输入 → 相同输出
✅ 无副作用：不修改任何外部状态
✅ 返回新数组：完全 Immutable
✅ 易于测试：可以独立测试

改进 handleConfirm：清晰的数据流

// ✅ 清晰的数据流
async handleConfirm() {
  // ... 验证逻辑
  
  // 根据不同编辑模式获取修改后的新数据
  let updatedData;
  if (this.editRowKey && !this.mergeByCarrier) {
    updatedData = this.applySingleRowEdit(shouldClear);
  } else if (this.editRowKey && this.mergeByCarrier) {
    updatedData = this.applyMergedEdit(shouldClear);
  } else {
    updatedData = this.applyBatchEdit(shouldClear);
  }
  
  // 返回修改后的完整数据数组
  this.$emit("confirm", updatedData);
}copy success

数据流示意：

srcData (原始副本，永不修改)
    ↓
applySingleRowEdit() → newData (返回新数组)
    ↓
emit("confirm", newData)
    ↓
父组件接收新数组
copy success

第二阶段成果

三个纯函数：

applySingleRowEdit(shouldClear) - 返回单行编辑后的新数组
applyMergedEdit(shouldClear) - 返回合并编辑后的新数组
applyBatchEdit(shouldClear) - 返回批量编辑后的新数组

优势对比：

维度	第一阶段	第二阶段
Immutability	部分	完全 ⭐
函数纯度	有副作用	纯函数 ⭐
数据流清晰度	较好	优秀 ⭐
可测试性	一般	优秀 ⭐
Vue 依赖	依赖 $set	纯 JS ⭐
函数式风格	命令式	声明式 ⭐

五、技术深度解析

1. 为什么使用 `map` 而不是 `forEach`？

// ❌ 命令式（forEach）
applyBatchEdit(shouldClear) {
  this.srcData.forEach((row, index) => {
    if (row.isChecked) {
      this.$set(this.srcData, index, { ...row, ...result });
    }
  });
}

// ✅ 声明式（map）
applyBatchEdit(shouldClear) {
  return this.srcData.map((row) => {
    if (row.isChecked) {
      return { ...row, ...result, isChecked: false };
    }
    return row;
  });
}copy success

map 的优势：

返回新数组，不修改原数组
声明式：描述"做什么"而非"怎么做"
链式调用友好
更符合函数式编程范式

2. 性能考量：深拷贝真的慢吗？

实测数据（200 条记录）：

深拷贝耗时：~5ms
map 遍历耗时：~1ms
总体耗时：< 10ms

结论：

对于中小规模数据（< 1000 条），性能差异可忽略
代码质量提升带来的长期收益远大于微小的性能损失
如果真的需要优化，可以考虑：
- 使用 structuredClone（浏览器原生）
- 使用 lodash.cloneDeep
- 使用 Immer.js

3. 边界情况处理

优秀的代码需要考虑边界情况：

applySingleRowEdit(shouldClear) {
  const targetRowIndex = this.srcData.findIndex(/* ... */);
  
  // ✅ 边界处理：找不到行时返回原数组
  if (targetRowIndex === -1) return this.srcData;
  
  return this.srcData.map(/* ... */);
}copy success

其他边界情况：

空数据：open(null) → 早期返回
无选中行：applyBatchEdit → 自动跳过
取消弹窗：不触发 confirm 事件

4. 规则配置清除的巧妙处理

业务需求：
当用户配置规则后又取消，需要清除历史字段，否则会影响表格合并功能。

问题场景：

// 新加坡行（从未配置）
{ carrierAccountId: 5, carrierPlanId: 12 }

// 中国行（配置后取消）
{ 
  carrierAccountId: 5, 
  carrierPlanId: 12,
  affiliateCardCarrierAccountId: 16, // ← 历史残留字段
  affiliateCardCarrierPlanId: 23      // ← 历史残留字段
}copy success

问题：

两行运营商和套餐相同
但因为中国行有历史字段，被判定为不同配置
表格无法合并

解决方案：

const result = shouldApplyRuleConfig
  ? { ...this.ruleConfigFormData, ...this.formData }
  : { 
      ...this.cloneDefaultRuleConfig(), // ← 关键：用默认值覆盖
      ...this.formData 
    };copy success

原理：

// 默认配置
{
  toggle: 0,
  noUseJudgeCount: 3,
  affiliateCardCarrierAccountId: undefined, // ← undefined 覆盖旧值
  affiliateCardCarrierPlanId: undefined      // ← undefined 覆盖旧值
}

// 覆盖后
{
  carrierAccountId: 5,
  carrierPlanId: 12,
  toggle: 0,
  affiliateCardCarrierAccountId: undefined, // ← 旧值 16 被覆盖
  affiliateCardCarrierPlanId: undefined      // ← 旧值 23 被覆盖
}copy success

现在新加坡行和中国行的数据结构完全一致，可以正常合并！

六、实践建议

1. 何时应该重构？

适合重构的信号：

❌ 需要手动 forceUpdate()
❌ 数据变更难以追踪
❌ 组件间耦合严重
❌ 难以编写单元测试
❌ 代码审查时频繁出现问题

2. 重构的步骤

推荐的渐进式重构：

第一步：添加完善的注释和文档
第二步：引入深拷贝，避免直接修改引用
第三步：改用事件驱动，返回完整数据
第四步：改用纯函数，返回新数组
第五步：编写单元测试，验证正确性

3. 团队协作建议

代码审查要点：

// ❌ 需要在代码审查中指出
props: ['data'],
methods: {
  modify() {
    this.data.push(item); // 直接修改 props
  }
}

// ✅ 推荐的做法
props: ['data'],
methods: {
  modify() {
    const newData = [...this.data, item];
    this.$emit('update', newData);
  }
}copy success

4. 性能优化建议

针对大数据量场景：

// 如果数据量 > 1000 条，考虑优化

// 方案 1：使用 structuredClone（现代浏览器）
this.srcData = structuredClone(srcData);

// 方案 2：使用 lodash
import cloneDeep from 'lodash/cloneDeep';
this.srcData = cloneDeep(srcData);

// 方案 3：使用 Immer（大型应用）
import produce from 'immer';
const newData = produce(this.srcData, draft => {
  draft[index] = newValue;
});copy success

七、总结与反思

重构成果

代码质量提升：

可读性：从 3/5 提升到 5/5
可维护性：从 3/5 提升到 5/5
可测试性：从 2/5 提升到 5/5
性能：保持在可接受范围（< 10ms）

架构改进：

旧架构：命令式 + 有副作用 + 紧耦合
    ↓
新架构：声明式 + 纯函数 + 松耦合
copy success

技术收获

深入理解 Vue 响应式原理
- Props 应该是只读的
- 数据流应该是单向的
- 响应式更新是自动的
掌握函数式编程思想
- Immutability（不可变性）
- Pure Function（纯函数）
- Declarative（声明式）
提升代码设计能力
- 单一职责原则
- 开闭原则
- 依赖倒置原则

给初学者的建议

不要害怕重构

重构是持续改进的过程
好的代码是迭代出来的
每次重构都是学习机会

遵循最佳实践

阅读官方文档
学习优秀开源项目
参与代码审查

保持好奇心

问自己"为什么"
尝试不同的实现方式
总结和分享经验

八、参考资料

Vue 官方文档

函数式编程

工具库

Immer.js - Immutable 数据处理
Lodash - 工具函数库
structuredClone - 原生深拷贝

Nunjucks快速指南

SunZhongyi — Wed, 31 Dec 2025 00:00:00 GMT

Nunjucks (.njk) 是 Mozilla 开发的一个功能强大的 JavaScript 模板引擎。它深受 Python 的 Jinja2 启发。如果你用过 Python 的 Jinja2 或 Django 模板，你会觉得非常亲切。

这份指南分为 基础语法、逻辑控制、高级复用 和 常用过滤器 四个部分。

1.1 核心概念：两种标签

Nunjucks 最基本的语法只有两种符号：

{{ }}：输出变量。会把结果打印到页面上。
{% %}：执行逻辑。用于循环、判断、定义变量，不会直接输出内容。

1.2 基础语法 (Variables)

1. 输出变量

{{ username }}
{{ user.id }}          <!-- 点语法访问属性 -->
{{ user['email'] }}    <!-- 括号语法访问属性 -->copy success

2. 设置默认值 (防止报错)

如果变量不存在，可以使用 default 过滤器：

Hello, {{ username | default("Guest") }}copy success

3. 定义变量 (Set)

在模板内部定义新变量：

{% set active_class = "is-active" %}
<div class="{{ active_class }}">...</div>copy success

1.3 逻辑控制 (Control Flow)

1. 条件判断 (If / Else)

{% if user.is_admin %}
  <button>Delete User</button>
{% elif user.is_editor %}
  <button>Edit User</button>
{% else %}
  <p>You have read-only access.</p>
{% endif %}copy success

2. 循环 (Loops)

遍历数组或对象：

<ul>
{% for item in items %}
  <li>
    {{ loop.index }} - {{ item.title }}
    <!-- loop.index 从 1 开始，loop.index0 从 0 开始 -->
    <!-- loop.first (是否是第一个), loop.last (是否是最后一个) -->
  </li>
{% else %}
  <li>这里没有数据 (当 items 为空时显示)</li>
{% endfor %}
</ul>copy success

1.4 过滤器 (Filters)

过滤器用于修改变量的输出，使用管道符 |。

常用内置过滤器

safe：最重要！ 不转义 HTML（渲染 HTML 字符串）。
```
{{ content_html | safe }}copy success
```

length：获取数组或字符串长度。

Count: {{ items | length }}copy success

upper / lower：大小写转换。

{{ "hello" | upper }}  <!-- 输出 HELLO -->copy success

join：连接数组。

{{ ["a", "b", "c"] | join("-") }} <!-- 输出 a-b-c -->copy success

replace：替换字符串。

{{ "Hello World" | replace("World", "Nunjucks") }}copy success

truncate：截断长文本。

{{ description | truncate(50) }}copy success

链式调用：

{{ "hello world" | upper | replace("WORLD", "NJK") }}copy success

1.5 模板继承 (Inheritance) —— Nunjucks 的灵魂

这是 Nunjucks 最强大的地方，用于构建统一的网站布局。

1. 定义父模板 (`layout.njk`)

使用 block 定义“坑位”，留给子页面去填。

<!-- layout.njk -->
<!DOCTYPE html>
<html>
<head>
  <title>{% block title %}默认标题{% endblock %}</title>
</head>
<body>
  <nav>导航栏</nav>

  <main>
    <!-- 这里是一个坑，名字叫 content -->
    {% block content %}{% endblock %}
  </main>

  <footer>页脚</footer>
</body>
</html>copy success

2. 定义子页面 (`page.njk`)

使用 extends 继承父模板，并把内容填入对应的 block。

<!-- page.njk -->
{% extends "layout.njk" %}

{% block title %}我的首页{% endblock %}

{% block content %}
  <h1>欢迎来到我的网站</h1>
  <p>这是正文内容。</p>
{% endblock %}copy success

1.6 组件与复用 (Macros ### 六、组件与复用 (Macros & Includes) Includes)

1. Include (简单引入)

直接把另一个文件的内容粘贴过来，适合页眉、页脚。

{% include "footer.njk" %}copy success

2. Macro (宏/组件)

类似于编程语言中的函数，用于生成可复用的 HTML 片段（如表单控件、卡片）。

定义宏 (forms.njk)：

{% macro input(name, placeholder, type="text") %}
  <div class="field">
    <input type="{{ type }}" name="{{ name }}" placeholder="{{ placeholder }}">
  </div>
{% endmacro %}copy success

使用宏：

{% import "forms.njk" as forms %}

<form>
  {{ forms.input("username", "请输入用户名") }}
  {{ forms.input("password", "请输入密码", "password") }}
</form>copy success

1.7 空白控制 (Whitespace Control)

Nunjucks 默认会保留代码中的换行符和空格。如果你想生成紧凑的代码，可以使用减号 -。

{%- ：去除标签左边的空白。
-%} ：去除标签右边的空白。

示例：

<!-- 假设 tags = [1, 2, 3] -->
[{% for i in tags -%}
  {{ i }}
{%- endfor %}]copy success

输出： [123] (没有多余的空格和换行)

1.8 其他实用技巧

1. 原始块 (Raw)

如果你需要在页面上输出 {{ }} 这种符号（例如你在写 Vue.js 或 Handlebars 的教程），需要禁止 Nunjucks 解析：

{% raw %}
  这里的内容不会被 Nunjucks 解析：{{ variable }}
{% endraw %}copy success

2. 导入上下文

include 默认会把当前页面的所有变量传给被引入的文件。
如果不想传，可以禁用：

{% include "component.njk" without context %}copy success

总结速查表

功能	语法
输出	`{{ var }}`
逻辑	`{% if condition %} ... {% endif %}`
循环	`{% for item in items %} ... {% endfor %}`
过滤器	`{{ var
注释	`{# 这是一个注释 #}`
继承	`{% extends "layout.njk" %}`
定义块	`{% block name %} ... {% endblock %}`
引入	`{% include "file.njk" %}`
转义HTML	`{{ html_str

WebRTC电视投屏实践踩坑实录: 从 SDP 解析失败到 mDNS 不可达

SunZhongyi — Thu, 19 Feb 2026 00:00:00 GMT

一、背景

我做了一个基于 WebRTC 的局域网屏幕共享工具，架构很简单：

Node.js + Express + Socket.IO 做信令服务器
浏览器端用原生 WebRTC API
Mac 上 Chrome 分享屏幕，局域网内其他设备打开网页观看

Mac 和手机都能正常观看，但电视上死活不行。电视用的是 TVBro 浏览器，内核是 Android WebView。

二、第一个障碍：看不到错误信息

电视浏览器没有 DevTools，看不到 console 输出。第一步是搭建远程调试能力。

我做了三件事：

2.1 屏幕内日志面板

劫持 console.log/error/warn，把所有输出渲染到页面上的一个 debug panel：

const origLog = console.log;
console.log = (...args) => {
    addLog(args.join(" "), "info");
    origLog(...args);
};copy success

2.2 日志编码系统

给每条日志加短代码（S01、B05、W99 等），这样在电视上看到错误时，只需要报 "W99: xxx" 就能快速定位：

[S01] Socket connected
[B05] Watcher connected: abc123
[W99] Offer handling error: Failed to parse SessionDescription...
copy success

2.3 服务器端日志文件

客户端通过 Socket.IO 把日志发送到服务器，写入 logs/client.log（JSON 格式，包含时间戳、socketId、UA 等），这样不用盯着电视屏幕也能分析问题。

三、第一个坑：`a=extmap-allow-mixed` SDP 解析失败

3.1 现象

电视端报错：

[W99] Offer handling error: Failed to parse SessionDescription.
      a=extmap-allow-mixed Expects at least 2 fields.
[W99a] Error name: OperationError
copy success

Mac 和手机完全正常。

3.2 原因

电视的 WebView 内核版本太旧。从 User-Agent 看到：

Chrome/96.0.4664.45   （电视）
Chrome/145.0.0.0      （Mac）
copy success

a=extmap-allow-mixed 是 Chrome 71+ 引入的 SDP 属性。旧版内核在 setRemoteDescription() 时遇到不认识的属性格式会直接抛 OperationError。

3.3 尝试过的弯路

adapter.js：Google 官方的 WebRTC 兼容层。但它的最新版本内部调用了 RTCPeerConnection.getConfiguration()，这个 API 在 Chrome 69 之前不存在，反而在电视上报了新错误 this.getConfiguration is not a function。对于这么老的内核，adapter.js 帮不上忙。

3.4 最终修复

在 setRemoteDescription 之前，手动过滤掉旧内核不认识的 SDP 属性：

function cleanSDP(sdp) {
    if (!sdp) return sdp;
    const lines = sdp.split('\r\n');
    const cleaned = [];
    for (const line of lines) {
        if (line === 'a=') continue;
        if (line.startsWith('a=extmap-allow-mixed')) continue;
        cleaned.push(line);
    }
    return cleaned.join('\r\n');
}

// 使用
const cleanedOffer = { type: offer.type, sdp: cleanSDP(offer.sdp) };
await pc.setRemoteDescription(cleanedOffer);copy success

修复后，SDP 解析通过了，信令流程完全正常（W07 → W08 → W09 → W10 → W11 全部成功），ontrack 也触发了。

但是——还是没有画面。

四、第二个坑：mDNS ICE Candidate 不可达

4.1 现象

SDP 问题解决后，日志显示信令完全成功，但 ICE 连接状态在 checking 15 秒后变成 failed：

[W03] ICE state: checking
...（15秒后）
[W03] ICE state: failed
copy success

4.2 排查

给 ICE candidate 加了详细日志，打印实际的候选地址：

pc.onicecandidate = (e) => {
    if (e.candidate) {
        addLog(`[B08] ICE candidate: ${e.candidate.candidate.substring(0, 80)}`);
    }
};copy success

日志揭示了真相：

// Mac 发出的 host candidate：
candidate:... 920bd423-1562-444b-b660-3be038f1de7c.local 54321 typ host

// 电视发出的 host candidate：
candidate:... 192.168.0.100 43375 typ host
copy success

Mac 的 host candidate 用的是 mDNS 地址（xxx.local），不是真实的局域网 IP 192.168.0.119。

4.3 原因

Chrome 75+ 引入了 WebRTC IP 隐私保护（spec），默认用 mDNS 地址替代真实的本地 IP，防止网页通过 WebRTC 泄露用户的局域网 IP。

现代浏览器能通过 mDNS 协议解析 .local 地址，所以 Mac 对 Mac、手机对 Mac 都没问题。但电视的旧版 WebView 不支持 mDNS 解析，收到 xxx.local 后无法找到对应的 IP，ICE 连接自然建立不起来。

唯一能用的候选是 STUN 返回的 srflx candidate（公网 IP 117.152.179.230），但局域网内走公网 IP 需要路由器支持 hairpin NAT，大多数家用路由器不支持。

4.4 最终修复

在信令服务器转发 ICE candidate 时，检测 .local 地址并替换为发送者的真实 LAN IP：

socket.on("candidate", (id, candidate) => {
    if (candidate && candidate.candidate && candidate.candidate.includes('.local')) {
        let senderIP = socket.handshake.address;
        if (senderIP === '::1' || senderIP === '127.0.0.1' || senderIP === '::ffff:127.0.0.1') {
            senderIP = getLocalIPv4Address();
        } else {
            senderIP = senderIP.replace('::ffff:', '');
        }
        candidate = {
            ...candidate,
            candidate: candidate.candidate.replace(/[a-f0-9-]+\.local/g, senderIP)
        };
    }
    io.to(id).emit("candidate", socket.id, candidate);
});copy success

这个修复利用了一个事实：信令服务器知道每个客户端的真实 IP（从 socket 连接获取），可以在转发时做地址替换。

修复后：

[W03] ICE state: checking
[B07] ICE state: connected     ← Mac 端连接成功
[B06] Connection state: connected
[W03] ICE state: connected     ← 电视端连接成功
copy success

电视终于有画面了。

五、总结

两个问题，两个不同的层面：

问题	层面	原因	修复位置
`a=extmap-allow-mixed` 解析失败	SDP 协议兼容	旧内核不认识新 SDP 属性	客户端（过滤 SDP）
mDNS candidate 不可达	ICE 网络连接	旧内核不支持 mDNS 解析	服务器端（替换地址）

5.1 远程调试能力是第一优先级

没有日志，一切都是盲猜。屏幕内 debug panel + 服务器端日志文件的组合在无 DevTools 的设备上非常有效。

5.2 日志编码系统值得投入

给每条日志加短代码（W99、B08），在电视这种输入不便的设备上，报错时只需要说 "W99: xxx" 就够了，大幅降低沟通成本。

5.3 adapter.js 不是万能的

它解决的是 API 层面的差异（比如 webkitRTCPeerConnection vs RTCPeerConnection），对于 SDP 语法兼容和 mDNS 这类底层问题无能为力。而且它的最新版本本身可能就不兼容太老的内核。

5.4 mDNS 是个隐蔽的坑

在同一局域网内，你会理所当然地认为 ICE 应该直接用局域网 IP 连接。但 Chrome 75+ 的隐私保护把真实 IP 藏在了 mDNS 后面，如果对端不支持 mDNS 解析，连接就会静默失败——没有明确的错误信息，只有 ICE state 从 checking 变成 failed。

5.5 信令服务器是做兼容的好地方

它是所有消息的中转站，知道每个客户端的真实 IP，可以在转发 SDP 和 ICE candidate 时做必要的修改，而不需要改动客户端代码。

六、最终架构

Mac (Chrome 145)                    TV (Chrome 96 WebView)
     |                                      |
     |  1. Share Screen                     |
     |  2. socket.emit("broadcaster")       |
     |                                      |  3. socket.emit("watcher")
     |  4. createOffer()                    |
     |  5. emit("offer", sdp)              |
     |          ↓                           |
     |    [信令服务器]                       |
     |    - 转发 offer                      |
     |          ↓                           |
     |                          6. cleanSDP(sdp)  ← 过滤 extmap-allow-mixed
     |                          7. setRemoteDescription()
     |                          8. createAnswer()
     |                          9. emit("answer")
     |                                      |
     |  10. emit("candidate")              |
     |          ↓                           |
     |    [信令服务器]                       |
     |    - 检测 .local                     |
     |    - 替换为真实 LAN IP  ← mDNS 修复  |
     |          ↓                           |
     |                          11. addIceCandidate()
     |                                      |
     |  ←——— P2P 视频流（直连）———→         |
copy success

WebRTC电视投屏实践踩坑实录: 从 SDP 解析失败到 mDNS 不可达

SunZhongyi — Thu, 19 Feb 2026 00:00:00 GMT

一、背景

我做了一个基于 WebRTC 的局域网屏幕共享工具，架构很简单：

Node.js + Express + Socket.IO 做信令服务器
浏览器端用原生 WebRTC API
Mac 上 Chrome 分享屏幕，局域网内其他设备打开网页观看

Mac 和手机都能正常观看，但电视上死活不行。电视用的是 TVBro 浏览器，内核是 Android WebView。

二、第一个障碍：看不到错误信息

电视浏览器没有 DevTools，看不到 console 输出。第一步是搭建远程调试能力。

我做了三件事：

2.1 屏幕内日志面板

劫持 console.log/error/warn，把所有输出渲染到页面上的一个 debug panel：

const origLog = console.log;
console.log = (...args) => {
    addLog(args.join(" "), "info");
    origLog(...args);
};copy success

2.2 日志编码系统

给每条日志加短代码（S01、B05、W99 等），这样在电视上看到错误时，只需要报 "W99: xxx" 就能快速定位：

[S01] Socket connected
[B05] Watcher connected: abc123
[W99] Offer handling error: Failed to parse SessionDescription...
copy success

2.3 服务器端日志文件

客户端通过 Socket.IO 把日志发送到服务器，写入 logs/client.log（JSON 格式，包含时间戳、socketId、UA 等），这样不用盯着电视屏幕也能分析问题。

三、第一个坑：`a=extmap-allow-mixed` SDP 解析失败

3.1 现象

电视端报错：

[W99] Offer handling error: Failed to parse SessionDescription.
      a=extmap-allow-mixed Expects at least 2 fields.
[W99a] Error name: OperationError
copy success

Mac 和手机完全正常。

3.2 原因

电视的 WebView 内核版本太旧。从 User-Agent 看到：

Chrome/96.0.4664.45   （电视）
Chrome/145.0.0.0      （Mac）
copy success

a=extmap-allow-mixed 是 Chrome 71+ 引入的 SDP 属性。旧版内核在 setRemoteDescription() 时遇到不认识的属性格式会直接抛 OperationError。

3.3 尝试过的弯路

adapter.js：Google 官方的 WebRTC 兼容层。但它的最新版本内部调用了 RTCPeerConnection.getConfiguration()，这个 API 在 Chrome 69 之前不存在，反而在电视上报了新错误 this.getConfiguration is not a function。对于这么老的内核，adapter.js 帮不上忙。

3.4 最终修复

在 setRemoteDescription 之前，手动过滤掉旧内核不认识的 SDP 属性：

function cleanSDP(sdp) {
    if (!sdp) return sdp;
    const lines = sdp.split('\r\n');
    const cleaned = [];
    for (const line of lines) {
        if (line === 'a=') continue;
        if (line.startsWith('a=extmap-allow-mixed')) continue;
        cleaned.push(line);
    }
    return cleaned.join('\r\n');
}

// 使用
const cleanedOffer = { type: offer.type, sdp: cleanSDP(offer.sdp) };
await pc.setRemoteDescription(cleanedOffer);copy success

修复后，SDP 解析通过了，信令流程完全正常（W07 → W08 → W09 → W10 → W11 全部成功），ontrack 也触发了。

但是——还是没有画面。

四、第二个坑：mDNS ICE Candidate 不可达

4.1 现象

SDP 问题解决后，日志显示信令完全成功，但 ICE 连接状态在 checking 15 秒后变成 failed：

[W03] ICE state: checking
...（15秒后）
[W03] ICE state: failed
copy success

4.2 排查

给 ICE candidate 加了详细日志，打印实际的候选地址：

pc.onicecandidate = (e) => {
    if (e.candidate) {
        addLog(`[B08] ICE candidate: ${e.candidate.candidate.substring(0, 80)}`);
    }
};copy success

日志揭示了真相：

// Mac 发出的 host candidate：
candidate:... 920bd423-1562-444b-b660-3be038f1de7c.local 54321 typ host

// 电视发出的 host candidate：
candidate:... 192.168.0.100 43375 typ host
copy success

Mac 的 host candidate 用的是 mDNS 地址（xxx.local），不是真实的局域网 IP 192.168.0.119。

4.3 原因

Chrome 75+ 引入了 WebRTC IP 隐私保护（spec），默认用 mDNS 地址替代真实的本地 IP，防止网页通过 WebRTC 泄露用户的局域网 IP。

唯一能用的候选是 STUN 返回的 srflx candidate（公网 IP 117.152.179.230），但局域网内走公网 IP 需要路由器支持 hairpin NAT，大多数家用路由器不支持。

4.4 最终修复

在信令服务器转发 ICE candidate 时，检测 .local 地址并替换为发送者的真实 LAN IP：

socket.on("candidate", (id, candidate) => {
    if (candidate && candidate.candidate && candidate.candidate.includes('.local')) {
        let senderIP = socket.handshake.address;
        if (senderIP === '::1' || senderIP === '127.0.0.1' || senderIP === '::ffff:127.0.0.1') {
            senderIP = getLocalIPv4Address();
        } else {
            senderIP = senderIP.replace('::ffff:', '');
        }
        candidate = {
            ...candidate,
            candidate: candidate.candidate.replace(/[a-f0-9-]+\.local/g, senderIP)
        };
    }
    io.to(id).emit("candidate", socket.id, candidate);
});copy success

这个修复利用了一个事实：信令服务器知道每个客户端的真实 IP（从 socket 连接获取），可以在转发时做地址替换。

修复后：

[W03] ICE state: checking
[B07] ICE state: connected     ← Mac 端连接成功
[B06] Connection state: connected
[W03] ICE state: connected     ← 电视端连接成功
copy success

电视终于有画面了。

五、总结

两个问题，两个不同的层面：

问题	层面	原因	修复位置
`a=extmap-allow-mixed` 解析失败	SDP 协议兼容	旧内核不认识新 SDP 属性	客户端（过滤 SDP）
mDNS candidate 不可达	ICE 网络连接	旧内核不支持 mDNS 解析	服务器端（替换地址）

Mac (Chrome 145)                    TV (Chrome 96 WebView)
     |                                      |
     |  1. Share Screen                     |
     |  2. socket.emit("broadcaster")       |
     |                                      |  3. socket.emit("watcher")
     |  4. createOffer()                    |
     |  5. emit("offer", sdp)              |
     |          ↓                           |
     |    [信令服务器]                       |
     |    - 转发 offer                      |
     |          ↓                           |
     |                          6. cleanSDP(sdp)  ← 过滤 extmap-allow-mixed
     |                          7. setRemoteDescription()
     |                          8. createAnswer()
     |                          9. emit("answer")
     |                                      |
     |  10. emit("candidate")              |
     |          ↓                           |
     |    [信令服务器]                       |
     |    - 检测 .local                     |
     |    - 替换为真实 LAN IP  ← mDNS 修复  |
     |          ↓                           |
     |                          11. addIceCandidate()
     |                                      |
     |  ←——— P2P 视频流（直连）———→         |
copy success