普通视图

发现新文章，点击刷新页面。

今天 — 2026年3月18日掘金前端

Rust宏编程完全指南：用元编程解锁Rust的终极力量

掘金前端

作者土豆1250

2026年3月18日 02:14

"宏就像是编译器的魔法棒，挥一挥，重复的代码就消失了。" —— 某位深夜 debug 的 Rustacean

Why：为什么需要宏？

想象一下，你正在写一个 Web 框架，需要为 50 个不同的结构体实现相同的序列化逻辑。如果用函数，你会发现自己陷入了"复制粘贴地狱"。如果用泛型，又会因为 Rust 严格的类型系统而撞墙。这时候，宏就像超级英雄一样闪亮登场了！

宏解决的核心问题

1. 消除重复代码（DRY 原则的终极武器）

// 没有宏之前，你可能要写：
impl ToString for User { /* ... */ }
impl ToString for Product { /* ... */ }
impl ToString for Order { /* ... */ }
// 写到第 50 个的时候，你已经怀疑人生了

// 有了宏：
#[derive(ToString)]
struct User { /* ... */ }
// 搞定！

2. 编译时计算（零运行时开销）

宏在编译期展开，这意味着：

没有运行时性能损失
错误在编译时就能发现
生成的代码可以被编译器完全优化

3. 创建 DSL（领域特定语言）

// 比如 vec! 宏让你写出这样优雅的代码：
let v = vec![1, 2, 3, 4, 5];

// 而不是：
let mut v = Vec::new();
v.push(1);
v.push(2);
v.push(3);
v.push(4);
v.push(5);

4. 超越泛型的抽象能力

泛型很强大，但它有局限：

泛型要求类型在运行时已知
泛型受 trait bounds 约束
宏可以操作任意语法，甚至可以生成新的类型

What：宏是什么？

在 Rust 中，宏是编写生成代码的代码（元编程）。但与 C 语言的简单文本替换不同，Rust 的宏操作的是抽象语法树（AST），这让它们既强大又安全。

Rust 宏的家族树

Rust 宏
├── 声明宏 (Declarative Macros)
│   └── macro_rules! - 基于模式匹配的宏
│
└── 过程宏 (Procedural Macros)
    ├── 派生宏 (Derive Macros) - #[derive(Trait)]
    ├── 属性宏 (Attribute Macros) - #[attribute]
    └── 函数式宏 (Function-like Macros) - macro!(...)

核心概念：TokenStream

宏的输入和输出都是 TokenStream（标记流），它是 Rust 代码的抽象表示：

// 这段代码对编译器来说是一个 TokenStream
let x: i32 = 42;

// 分解成 tokens:
// [let] [x] [:] [i32] [=] [42] [;]

How：如何使用宏？

1. 声明宏 (macro_rules!)

声明宏是最容易入门的宏类型，它使用模式匹配语法，就像一个超级版的 match 表达式。

1.1 基础语法

macro_rules! say_hello {
    // () 表示宏不接受参数
    () => {
        println!("Hello, Rustacean!");
    };
}

fn main() {
    say_hello!(); // 输出: Hello, Rustacean!
}

1.2 接受参数

宏使用片段说明符（fragment specifiers）来匹配不同类型的语法元素：

说明符	匹配内容	示例
`expr`	表达式	`1 + 2`, `foo()`
`ident`	标识符	`x`, `my_var`
`ty`	类型	`i32`, `Vec<String>`
`pat`	模式	`Some(x)`, `_`
`stmt`	语句	`let x = 5;`
`block`	代码块	`{ /* ... */ }`
`item`	项	`fn foo() {}`, `struct Bar;`
`tt`	Token树	任何标记

实例：创建一个 HashMap 初始化宏

macro_rules! hashmap {
    // 匹配 key => value 对，逗号分隔
    ($($key:expr => $value:expr),* $(,)?) => {
        {
            let mut map = ::std::collections::HashMap::new();
            $(
                map.insert($key, $value);
            )*
            map
        }
    };
}

fn main() {
    let scores = hashmap! {
        "Alice" => 95,
        "Bob" => 87,
        "Charlie" => 92,
    };
    
    println!("{:?}", scores);
}

语法分析：

$( ... )* - 零次或多次重复
$(,)? - 可选的尾随逗号
$key:expr - 捕获一个表达式并命名为 key

1.3 多模式匹配

macro_rules! calculate {
    // 加法
    (add $a:expr, $b:expr) => {
        $a + $b
    };
    
    // 乘法
    (mul $a:expr, $b:expr) => {
        $a * $b
    };
    
    // 多个数字求和
    (sum $($num:expr),+) => {
        {
            let mut total = 0;
            $(
                total += $num;
            )+
            total
        }
    };
}

fn main() {
    println!("{}", calculate!(add 10, 20));        // 30
    println!("{}", calculate!(mul 5, 6));          // 30
    println!("{}", calculate!(sum 1, 2, 3, 4, 5)); // 15
}

1.4 实战案例：类型安全的单位转换

macro_rules! unit_converter {
    ($value:expr, $from:ident to $to:ident) => {
        match (stringify!($from), stringify!($to)) {
            ("meters", "feet") => $value * 3.28084,
            ("feet", "meters") => $value / 3.28084,
            ("kg", "pounds") => $value * 2.20462,
            ("pounds", "kg") => $value / 2.20462,
            _ => panic!("不支持的单位转换: {} to {}", 
                       stringify!($from), stringify!($to)),
        }
    };
}

fn main() {
    let height_m = 1.75;
    let height_ft = unit_converter!(height_m, meters to feet);
    println!("{}米 = {:.2}英尺", height_m, height_ft);
}

2. 派生宏 (Derive Macros)

派生宏是最常用的过程宏类型，你肯定用过 #[derive(Debug, Clone)]！

2.1 工作原理

派生宏：

接收结构体/枚举的 TokenStream
分析其字段和类型
生成 trait 实现代码
不修改原始类型，只添加新代码

2.2 创建自定义派生宏

步骤 1：创建过程宏 crate

# Cargo.toml
[package]
name = "my_derive"
version = "0.1.0"
edition = "2021"

[lib]
proc-macro = true  # 关键：声明这是过程宏 crate

[dependencies]
syn = { version = "2.0", features = ["full"] }
quote = "1.0"
proc-macro2 = "1.0"

步骤 2：实现派生宏

// src/lib.rs
use proc_macro::TokenStream;
use quote::quote;
use syn::{parse_macro_input, DeriveInput};

#[proc_macro_derive(Builder)]
pub fn derive_builder(input: TokenStream) -> TokenStream {
    // 解析输入的结构体
    let input = parse_macro_input!(input as DeriveInput);
    let name = &input.ident;
    let builder_name = syn::Ident::new(
        &format!("{}Builder", name), 
        name.span()
    );
    
    // 提取字段
    let fields = if let syn::Data::Struct(data) = &input.data {
        if let syn::Fields::Named(fields) = &data.fields {
            &fields.named
        } else {
            panic!("Builder 只支持命名字段的结构体");
        }
    } else {
        panic!("Builder 只能应用于结构体");
    };
    
    // 生成 builder 字段（都是 Option）
    let builder_fields = fields.iter().map(|f| {
        let name = &f.ident;
        let ty = &f.ty;
        quote! {
            #name: Option<#ty>
        }
    });
    
    // 生成 setter 方法
    let setters = fields.iter().map(|f| {
        let name = &f.ident;
        let ty = &f.ty;
        quote! {
            pub fn #name(mut self, #name: #ty) -> Self {
                self.#name = Some(#name);
                self
            }
        }
    });
    
    // 生成 build 方法
    let build_fields = fields.iter().map(|f| {
        let name = &f.ident;
        quote! {
            #name: self.#name.ok_or(
                concat!("字段 ", stringify!(#name), " 未设置")
            )?
        }
    });
    
    // 使用 quote! 生成最终代码
    let expanded = quote! {
        pub struct #builder_name {
            #(#builder_fields,)*
        }
        
        impl #builder_name {
            #(#setters)*
            
            pub fn build(self) -> Result<#name, &'static str> {
                Ok(#name {
                    #(#build_fields,)*
                })
            }
        }
        
        impl #name {
            pub fn builder() -> #builder_name {
                #builder_name {
                    #(#name: None,)*
                }
            }
        }
    };
    
    TokenStream::from(expanded)
}

步骤 3：使用派生宏

use my_derive::Builder;

#[derive(Builder)]
struct User {
    username: String,
    email: String,
    age: u32,
}

fn main() {
    let user = User::builder()
        .username("rustacean".to_string())
        .email("rust@example.com".to_string())
        .age(25)
        .build()
        .unwrap();
        
    println!("{} ({}岁): {}", user.username, user.age, user.email);
}

2.3 处理泛型和生命周期

派生宏的一个常见陷阱是忘记处理泛型参数：

// 这个结构体有泛型参数
#[derive(Builder)]
struct Container<T> {
    value: T,
}

// 你的派生宏需要提取并保留泛型信息
let generics = &input.generics;
let (impl_generics, ty_generics, where_clause) = generics.split_for_impl();

let expanded = quote! {
    impl #impl_generics #name #ty_generics #where_clause {
        // ...
    }
};

3. 属性宏 (Attribute Macros)

属性宏可以附加到几乎任何 Rust 项上，并且可以修改或增强该项。

3.1 基础结构

#[proc_macro_attribute]
pub fn route(attr: TokenStream, item: TokenStream) -> TokenStream {
    // attr: 属性参数（如 #[route(GET, "/users")] 中的 GET, "/users"）
    // item: 被装饰的项（如函数定义）
    // 返回：替换后的代码
}

3.2 实战：创建一个计时宏

use proc_macro::TokenStream;
use quote::quote;
use syn::{parse_macro_input, ItemFn};

#[proc_macro_attribute]
pub fn timed(_attr: TokenStream, item: TokenStream) -> TokenStream {
    let input = parse_macro_input!(item as ItemFn);
    
    let fn_name = &input.sig.ident;
    let fn_block = &input.block;
    let fn_sig = &input.sig;
    let fn_vis = &input.vis;
    
    let output = quote! {
        #fn_vis #fn_sig {
            let _start = std::time::Instant::now();
            
            // 执行原始函数体
            let result = (|| #fn_block)();
            
            let _duration = _start.elapsed();
            println!("函数 {} 执行耗时: {:?}", 
                     stringify!(#fn_name), _duration);
            
            result
        }
    };
    
    TokenStream::from(output)
}

使用示例：

#[timed]
fn slow_computation() -> u64 {
    std::thread::sleep(std::time::Duration::from_secs(2));
    42
}

fn main() {
    let result = slow_computation();
    // 输出: 函数 slow_computation 执行耗时: 2.00s
    println!("结果: {}", result);
}

3.3 高级案例：带参数的属性宏

#[proc_macro_attribute]
pub fn cache(attr: TokenStream, item: TokenStream) -> TokenStream {
    let cache_size: usize = syn::parse_str(&attr.to_string())
        .expect("cache 参数必须是数字");
    
    let input = parse_macro_input!(item as ItemFn);
    
    // 生成带缓存功能的函数
    let expanded = quote! {
        // 使用 lazy_static 创建全局缓存
        lazy_static::lazy_static! {
            static ref CACHE: std::sync::Mutex<
                lru::LruCache<String, String>
            > = std::sync::Mutex::new(
                lru::LruCache::new(
                    std::num::NonZeroUsize::new(#cache_size).unwrap()
                )
            );
        }
        
        #input  // 保留原函数
        
        // 生成带缓存的包装函数
        // ... (实现细节)
    };
    
    TokenStream::from(expanded)
}

使用：

#[cache(100)]  // 缓存最多 100 个结果
fn expensive_api_call(query: &str) -> String {
    // 昂贵的计算...
}

4. 函数式宏 (Function-like Macros)

函数式宏看起来像函数调用，但实际上是在编译时展开。

4.1 基础示例

#[proc_macro]
pub fn sql(input: TokenStream) -> TokenStream {
    let query = input.to_string();
    
    // 在编译时验证 SQL 语法！
    validate_sql(&query).expect("无效的 SQL 语句");
    
    // 生成优化的查询执行代码
    let expanded = quote! {
        {
            let query = #query;
            execute_query(query)
        }
    };
    
    TokenStream::from(expanded)
}

使用：

fn main() {
    let users = sql!(SELECT * FROM users WHERE age > 18);
    // 如果 SQL 语法错误，编译就会失败！
}

4.2 实战：HTML 模板宏

macro_rules! html {
    // 匹配单个标签
    (<$tag:ident>$($content:tt)*</$close:ident>) => {
        {
            assert_eq!(
                stringify!($tag), 
                stringify!($close), 
                "标签不匹配"
            );
            format!("<{}>{}</{}>", 
                    stringify!($tag), 
                    html!($($content)*), 
                    stringify!($tag))
        }
    };
    
    // 匹配文本内容
    ($text:expr) => {
        $text.to_string()
    };
}

fn main() {
    let page = html!(
        <html>
            <body>
                <h1>"欢迎来到 Rust 世界！"</h1>
            </body>
        </html>
    );
    
    println!("{}", page);
}

最佳实践

1. 命名规范

// ✅ 好的命名
macro_rules! create_user { /* ... */ }        // 清晰的动词
#[derive(Serialize)]                          // 名词形式的 trait
#[validate(email)]                            // 描述性的属性

// ❌ 避免
macro_rules! x { /* ... */ }                  // 太短
#[do_stuff]                                   // 不明确

2. 错误处理

// ✅ 提供有用的错误信息
macro_rules! require_fields {
    ($struct_name:ident { $($field:ident),* }) => {
        compile_error!(concat!(
            "结构体 ", 
            stringify!($struct_name), 
            " 缺少必需字段: ",
            $(stringify!($field), ", "),*
        ));
    };
}

// ✅ 在过程宏中使用 panic! 或 syn::Error
#[proc_macro_derive(MyMacro)]
pub fn my_macro(input: TokenStream) -> TokenStream {
    let input = match syn::parse(input) {
        Ok(syntax_tree) => syntax_tree,
        Err(err) => return err.to_compile_error().into(),
    };
    // ...
}

3. 卫生性（Hygiene）

过程宏是非卫生的（unhygienic），这意味着它们可能与周围代码发生命名冲突：

// ❌ 危险：可能与用户代码冲突
quote! {
    let result = compute();
}

// ✅ 使用绝对路径
quote! {
    let __internal_result = ::my_crate::compute();
}

// ✅ 或使用 fully qualified syntax
quote! {
    let result = <Type as Trait>::method();
}

4. 文档化你的宏

/// 创建一个 HashMap 并初始化键值对
///
/// # 示例
///
/// ```
/// let map = hashmap! {
///     "key1" => "value1",
///     "key2" => "value2",
/// };
/// ```
#[macro_export]
macro_rules! hashmap {
    // ...
}

5. 测试宏

#[cfg(test)]
mod tests {
    use super::*;
    
    #[test]
    fn test_hashmap_macro() {
        let map = hashmap! {
            "a" => 1,
            "b" => 2,
        };
        assert_eq!(map.get("a"), Some(&1));
    }
    
    // 使用 trybuild 测试编译错误
    #[test]
    fn test_compile_errors() {
        let t = trybuild::TestCases::new();
        t.compile_fail("tests/invalid_usage.rs");
    }
}

6. 性能考虑

// ✅ 宏在编译时展开，没有运行时开销
let v = vec![1, 2, 3, 4, 5];

// ✅ 但要注意宏展开可能增加二进制大小
// 如果宏在很多地方调用且生成大量代码，考虑改用函数

常见误区

误区 1：宏可以做任何事

现实： 宏有明确的限制。

// ❌ 无法生成新的标识符名称（除非使用 paste 等技巧）
macro_rules! create_function {
    ($name:ident) => {
        fn $name_generated() {}  // 错误！不能拼接标识符
    };
}

// ✅ 需要使用 paste! crate
use paste::paste;

macro_rules! create_function {
    ($prefix:ident) => {
        paste! {
            fn [<$prefix _generated>]( "<$prefix _generated>") {}  // OK!
        }
    };
}

误区 2：忽略宏的顺序依赖

// ❌ 错误：宏还未定义
fn main() {
    my_macro!();
}

macro_rules! my_macro {
    () => { println!("Hello!"); };
}

// ✅ 正确：先定义宏
macro_rules! my_macro {
    () => { println!("Hello!"); };
}

fn main() {
    my_macro!();
}

误区 3：过度使用宏

问题代码：

// ❌ 这个可以用简单函数实现
macro_rules! add_two {
    ($x:expr) => {
        $x + 2
    };
}

// ✅ 更好的选择
const fn add_two(x: i32) -> i32 {
    x + 2
}

何时使用宏 vs 函数：

使用宏	使用函数
需要操作语法（如生成 trait 实现）	简单的值计算
需要在编译时验证某些条件	运行时逻辑
需要可变数量的参数类型	固定的参数类型
实现 DSL	普通业务逻辑

误区 4：不处理边界情况

// ❌ 没有处理空列表
macro_rules! first {
    ($($x:expr),+) => {
        $x  // 错误：哪个 $x？
    };
}

// ✅ 明确处理
macro_rules! first {
    ($first:expr $(, $rest:expr)*) => {
        $first
    };
}

误区 5：忘记递归限制

// ❌ 可能触发递归限制
macro_rules! recurse {
    () => {
        recurse!()  // 无限递归！
    };
}

// ✅ 如果需要深层递归，增加限制
#![recursion_limit = "256"]

调试技巧

1. 查看宏展开结果

# 使用 cargo expand（需要先安装）
cargo install cargo-expand

# 查看完整的宏展开
cargo expand

# 查看特定模块
cargo expand module_name

2. 使用 `dbg!` 宏

macro_rules! debug_macro {
    ($($x:expr),*) => {
        {
            $(
                dbg!($x);  // 在宏内部调试
            )*
        }
    };
}

3. 编译时打印

// 在过程宏中打印调试信息
eprintln!("Processing: {:?}", tokens);

实战综合案例：创建一个状态机宏

这个案例综合运用了多种宏技术：

// 定义状态机语法
macro_rules! state_machine {
    (
        $name:ident {
            states: [ $($state:ident),* $(,)? ]
            transitions: {
                $($from:ident => $to:ident on $event:ident),* $(,)?
            }
        }
    ) => {
        // 定义状态枚举
        #[derive(Debug, Clone, Copy, PartialEq)]
        enum $name {
            $($state),*
        }
        
        // 定义事件枚举
        paste::paste! {
            #[derive(Debug)]
            enum [<$name Event>] {
                $($event),*
            }
        }
        
        // 实现状态转换
        impl $name {
            fn transition(&self, event: &paste::paste!{[<$name Event>]}) -> Option<Self> {
                match (self, event) {
                    $(
                        (Self::$from, paste::paste!{[<$name Event>]::$event}) => {
                            Some(Self::$to)
                        }
                    )*
                    _ => None,
                }
            }
        }
    };
}

// 使用状态机宏
state_machine! {
    TrafficLight {
        states: [Red, Yellow, Green]
        transitions: {
            Red => Green on TimerExpired,
            Green => Yellow on TimerExpired,
            Yellow => Red on TimerExpired,
        }
    }
}

fn main() {
    let mut light = TrafficLight::Red;
    println!("初始状态: {:?}", light);
    
    light = light.transition(&TrafficLightEvent::TimerExpired).unwrap();
    println!("转换后: {:?}", light);  // Green
}

总结

宏是 Rust 的超能力，但也需要谨慎使用。记住这些要点：

✅ 使用宏的好时机

消除大量重复代码
创建 DSL 让代码更简洁
在编译时验证或生成代码
实现无法用泛型表达的抽象

❌ 避免使用宏的情况

简单的值计算（用函数）
普通的类型抽象（用泛型）
会让代码难以理解的地方

🎯 学习路径建议

初学者：从 macro_rules! 开始，理解模式匹配
进阶者：学习派生宏，理解 syn 和 quote
高级开发者：掌握属性宏和函数式宏，创建 DSL

📚 推荐资源

最后的忠告： 宏就像辣椒酱，适量使用能让你的代码美味可口，但过量使用会让人难以下咽。在写宏之前，问问自己："这个真的需要宏吗？" 如果答案是肯定的，那就大胆地挥舞你的元编程魔法棒吧！🪄✨

Happy macro coding, Rustaceans! 🦀

AI辅助开发最佳实践：2026年新方法

掘金前端

作者牛奶

2026年3月17日 23:50

这是系列第六篇。05篇我们讲了AI批量处理，这篇来看看怎么系统化管理AI配置，让AI真正成为你的开发助手。

上一篇文章，我们讲了怎么用AI批量处理重复工作。

这篇文章，我们来聊聊怎么系统化管理AI配置。

原文地址

墨渊书肆/AI辅助开发最佳实践：2026年新方法

如果你已经用AI辅助开发一段时间，可能会遇到这些问题：

每次都要重复说同样的话 — "用TypeScript"、"注意暗色模式"、"用Tailwind"
好的实践没法传承 — 踩过的坑、学到的技巧，用完就忘了
团队配置不统一 — 每个人都要从头配置

2026年的AI辅助开发已经有了成熟解决方案。这篇文章会告诉你如何把这些工具组合起来，打造属于自己的AI开发系统。

1. 为什么需要系统化的AI配置

1.1 传统方式的痛点

想象一下，你每次让AI写代码都要说：

"用TypeScript、React 19、Tailwind CSS、暗色模式、组件要tsx后缀、API错误返回success和error字段、禁止any..."

累不累？

配置好之后，你只需要说：

"帮我写个登录页面"

AI自动知道：TypeScript + React 19 + Tailwind + 暗色模式 + 统一错误格式

这就是系统化配置的价值。

1.2 系统化配置能做什么

能做到	说明
少说话多办事	一次配置，长期生效
团队一起用	配置文件提交Git，复制到新项目就行
经验不丢失	踩过的坑、学到的技巧都能沉淀下来
质量更稳定	规范化的代码，去哪都一致

2. 核心概念一览

先看个全貌，后面会一个个详细讲：

┌─────────────────────────────────────────────────────────┐
│                    你的 AI 开发助手                       │
├─────────────────────────────────────────────────────────┤
│  MCP     ──→ 给AI装上"手"和"脚"，能干活                  │
│  Rules   ──→ 制定"项目宪法"，让AI知道怎么做              │
│  Skills  ──→ 召唤"领域专家"，专门回答特定问题             │
│  Agents  ──→ 分配"专人负责"，处理特定任务                 │
│  Hooks   ──→ 设置"自动触发"，保存提交时执行               │
└─────────────────────────────────────────────────────────┘

3. MCP：给AI装上"手"和"脚"

3.1 MCP是什么

MCP的中文名字是"模型上下文协议"，太学术了。

换个说法：MCP就像给AI装上了手和脚。

以前AI只能跟你聊天，它不知道你电脑里有什么、你的项目长什么样。现在AI可以：

📁 读取你电脑上的文件
💻 执行终端命令
🗄️ 操作数据库
🌐 控制浏览器
🔧 帮你运行各种工具

3.2 怎么理解MCP

想象你在指挥一个人干活：

没有MCP：你只能跟AI说"帮我看看这个文件"，然后自己把文件内容复制粘贴给它
有了MCP：AI自己就能读取文件、自己执行命令、自己操作数据库

这就是为什么叫它"AI的USB接口" — 插上就能用，扩展AI的能力。

3.3 安装MCP

方式一：市场一键安装（推荐）:

Cursor 2.4+ 支持从市场安装，就像装Chrome插件一样简单：

1. 打开 Cursor 设置：Cmd + ,
2. 找到 "MCP" 或 "Extensions"
3. 点击 "Browse MCP Marketplace"
4. 搜索想要的 MCP，点击 "Add" 安装

方式二：手动配置:

有些MCP市场没有，只能自己配置。在项目根目录创建 .cursor/mcp.json：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}"]
    }
  }
}

这里 ${workspaceFolder} 是项目根目录的简写。

3.4 常用MCP推荐

主流MCP推荐（Cursor市场最火的）：

MCP工具	能做什么	什么时候用
Figma	设计稿转代码	看设计图写代码
Playwright / Puppeteer	浏览器自动化	E2E测试、爬虫、自动化操作
GitHub	代码仓库操作	管理PR、Issue、代码审查
Browsertools	浏览器调试	看控制台、网络请求、性能分析
Web Search	联网搜索	查资料、搜文档
Sequential Thinking	逐步思考	复杂问题帮你理清思路

4. Rules：制定"项目宪法"

4.1 Rules是什么

Rules就是"项目宪法"：告诉AI这个项目要怎么做。

比如你告诉AI：

我们用Next.js的App Router
默认用Server Components
暗色模式用dark:前缀
API错误格式统一用 { success: boolean, error?: string }

这些规则配置好之后，AI写的代码永远符合规范。

4.2 怎么理解Rules

想象你招了一个新同事，要告诉他团队规范：

口头说 — 每次都要说，说完就忘
写成文档 — 看不看取决于他
配置成Rules — AI永远记住，照着做

Rules就是把团队规范"固化"到AI里。

4.3 配置Rules

存放位置：

位置	谁能用到
`.cursor/rules/`	当前项目，提交Git后团队共享
`~/.cursor/rules/`	你所有项目都能用

文件格式：

用 .mdc 文件（推荐）：

---
name: nextjs
description: Next.js 15 App Router项目规范
globs: ["**/*"]
---

# Next.js 15 项目规范

## 技术栈
- 框架：Next.js 15 App Router
- 语言：TypeScript
- 样式：Tailwind CSS

## 代码规范
1. 默认使用Server Components
2. 客户端用'use client'标记
3. API错误格式统一

关键字段：

字段	什么意思
`name`	这个规则叫什么
`description`	什么时候用这个规则
`globs`	哪些文件要遵守这个规则，比如 `["*/.tsx"]`
`alwaysApply`	true=始终生效，false=需要时才用

4.4 怎么使用Rules

使用方式	怎么触发
始终生效	配置 `alwaysApply: true`
智能判断	AI根据你说的内容判断要不要用（默认）
匹配文件	当你编辑匹配的文件时自动应用
手动触发	聊天时 `@规则名` 来引用

5. Skills：召唤"领域专家"

5.1 Skills是什么

Skills是"领域专家"。你可以把AI配置成数据库专家、安全专家、TypeScript专家等等。

比如你配置了一个"数据库专家"Skill，当你问AI数据库相关问题时，它会自动用数据库专家的思维方式来回答。

5.2 怎么理解Skills

想象你有一个专家团队：

数据库专家 — 专门回答数据库问题，写SQL特别厉害
安全专家 — 专门检查代码安全问题
TypeScript专家 — 专门处理类型问题

每当需要专家时，AI就会"召唤"对应的技能。

5.3 配置Skills

存放位置：

位置	谁能用到
`.cursor/skills/`	当前项目
`~/.cursor/skills/`	你所有项目

目录结构：

.cursor/skills/
└── database/           # 一个Skill一个文件夹
    ├── SKILL.md       # 必填：技能定义
    ├── references/    # 可选：参考资料
    └── scripts/       # 可选：可执行脚本

SKILL.md格式：

---
name: database
description: 回答数据库相关问题时优先考虑性能
---

# 数据库专家

你是一个数据库专家，精通PostgreSQL、MySQL、Prisma。

## 回答原则
1. 优先考虑查询性能，避免N+1
2. 合理使用索引
3. 关联查询用include/preload

## 回答格式
先解释原理，再给代码示例

关键字段：

字段	什么意思
`name`	技能名字
`description`	用来判断什么时候召唤这个专家
`disable-model-invocation`	true=只有手动 `/skill-name` 才触发

5.4 怎么使用Skills

自动触发：AI根据你的问题判断该用什么技能
手动触发：输入 /数据库 来召唤数据库专家
查看有哪些技能：Settings → Rules → Agent Skills

6. Agents：分配"专人负责"

6.1 Agents是什么

Agents是"专人负责"。和Skills不同，Agents不是回答问题，而是帮你干活。

比如你配置了一个"代码审查Agent"，每次PR需要审查时，交给它来做。

6.2 怎么理解Agents

想象你有个小团队：

代码审查员 — 专门帮你审查代码
测试工程师 — 专门帮你写测试
文档写手 — 专门帮你写文档

你只需要分配任务，他们就会在自己的"工作区"里完成。

6.3 配置Agents

目录结构：

.cursor/agents/
└── code-review.md     # 一个Agent一个文件

格式：

---
name: code-review
description: 代码审查专家，审查PR和代码质量
model: fast
---

# 代码审查专家

你是一个代码审查专家。请审查以下代码：

1. 潜在问题
2. 性能优化点
3. 代码规范问题

## 输出格式
## 审查结果
## 问题列表
## 优化建议

model字段：

值	速度	适用场景
fast	快	简单任务、代码审查
balanced	平衡	大多数任务
smart	慢但聪明	复杂任务、架构设计

6.4 怎么使用Agents

自动委派：复杂任务来了，AI自动分配给合适的Agent
手动触发：输入 /agent-name 来调用

7. Hooks：设置"自动触发"

7.1 Hooks是什么

Hooks就是"自动触发器"。就像Git的hook在commit/push时自动运行脚本，AI的Hooks可以在特定事件发生时执行。

7.2 怎么理解Hooks

比如：

保存文件时 — 自动格式化代码
提交代码时 — 自动跑lint检查
新建组件时 — 自动套用模板

你不需要每次手动触发，AI帮你自动完成。

7.3 配置Hooks

创建 .cursor/hooks.json：

{
  "hooks": [
    {
      "match": ".*\\.(ts|tsx|js|jsx)$",
      "run": "npx prettier --write {file}"
    },
    {
      "match": ".*\\.(ts|tsx)$",
      "run": "npx eslint --fix {file}"
    }
  ]
}

这里的 {file} 会自动替换成实际文件路径。

8. 怎么组合使用

光知道概念没用，关键是怎么组合起来用。

8.1 一个典型的工作流

你：帮我写个用户管理模块

AI自动触发：
1. Rules → 知道项目用Next.js + TypeScript + Tailwind
2. Skills → 召唤数据库专家来处理数据层
3. MCP → 自己读取现有的用户表结构
4. Agents → 分配给代码生成Agent来写代码
5. Hooks → 写完后自动格式化

8.2 组合使用示例

@nextjs @skill database
帮我写一个用户管理模块，包含：
- 用户列表（分页）
- 用户CRUD
- 数据库优化

这个提示词同时触发了：

Next.js规范
数据库专家技能

AI会自动用数据库专家的角度来写代码，而且符合Next.js规范。

总结

概念	比喻	怎么用
MCP	手和脚	市场安装或配置 `.cursor/mcp.json`
Rules	项目宪法	配置 `.cursor/rules/`
Skills	领域专家	配置 `.cursor/skills/`
Agents	专人负责	配置 `.cursor/agents/`
Hooks	自动触发	配置 `.cursor/hooks.json`

把这五个工具组合起来，你的AI开发效率会大幅提升。赶紧去配置试试吧！

篇预告

这一篇我们讲完了AI辅助开发最佳实践。

下一阶段是《AI功能接入与网页开发》，我们会开始做真正的AI项目。

预告：下一篇文章，《Next.js里接入大模型聊天最简单的方法》。

感兴趣的话，下一篇见。

昨天 — 2026年3月17日掘金前端

AI 对话应用之 JS 的流式接口数据处理

掘金前端

作者 Setsuna_F_Seiei

2026年3月17日 22:54

需求背景

市面上的 AI 聊天软件基本上都是不断地向页面渲染出来 AI 思考的内容，传统的 web 网络 request 接口并不适合这种 ai 不断思考，不断输出内容的场景。而这种不断输出内容的应用场景最适合使用流式数据传输这种技术这不仅能够提升用户体验，还能优化数据传输效率，增强系统的可靠性和安全性；通过流式数据传输方案，满足用户对AI对话的多样化需求。

技术选型

而网页前端 js 当中针对流式数据的接收处理主流有以下几种形式：

Server-Sent Events (SSE)
WebSocket
fetch API + stream API

虽然有很多种 AI 对话处理的技术选型，但是其实还是取决于后台这次使用 java 的 Spring AI 返回的是 Stream 形式的数据，因此最后的技术选型使用的是fetch API + stream API。

具体实现与封装

原生 fetch api

其实使用 XMLRequest 也是能够实现接收 stream 流式数据的接口请求，只需要通过 api 当中的 onprogress 对接口返回的数据进行监听则可以实现；但是已经是现代化的应用了，我们可以使用更加现代化的 fetch api 进行开发处理。

声明设置 response 接收流式数据
组装数据发送请求

fetch("https://www.example.org", {
  method: 'post',
  headers: {
    Authorization: Token,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    xxx: 'yyy',
  }),
}).then((response) => {
  console.warn(response.body);
  // TODO: 进一步使用 Stream 处理流式数据 - 下一节介绍
});

处理流式 Stream 结果

在 node 当中对 stream 的流式数据处理有着原生能力支持处理，而在 web 浏览器当中想要对相关的流式数据处理则需要浏览器提供到相关的 ReadableStream API 能力支持进行处理。

ReadableStream MDN：developer.mozilla.org/zh-CN/docs/…

ReadableStream.getReader MDN：developer.mozilla.org/zh-CN/docs/…

在前面使用 fetch 发送能够接收 stream 流式数据的接口后，我们通过 response.body 拿到的对象是一个 ReadableStream 对象；
接着通过调用 ReadableStream.getReader() 这个方法得到一个 reader对象
通过reader对象的read方法能够返回一个 Promise 对象，Promise 的 resolve callback 当中则对流式数据进行多次调用读取数据块，进而实现对流式数据的处理。callback 当中的 response 数据结构包含done和value;
- 如果有分块可用，则 promise 将使用 { value: theChunk, done: false } 形式的对象来兑现。
- 如果流已经关闭，则 promise 将使用 { value: undefined, done: true } 形式的对象来兑现。
- 如果流发生错误，则 promise 将因相关错误被拒绝。

fetch("https://www.example.org", {
  method: 'post',
  headers: {
    Authorization: Token,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    xxx: 'yyy',
  }),
}).then((response) => {
  const reader = response.body.getReader();
  reader.read().then(({ done, value }) => {
    if (done) {
      return console.warn('read end', value);
    }

    return console.warn('reading', value);
  });
})

完整链路的封装

这里进行对相关的进一步封装，封装一个专门处理 stream 接口返回的FetchEventSource类：

增加取消处理

增加错误边界处理

因为流式数据是通过 Promise 的 resolve callback 不断多次返回处理的，因此这里我们并不能直接通过 Promise 的简单封装返回。

这里是提供两种处理方法：

1. callback 回调的形式处理

这种形式更加贴近 Node.js 原生的写法形式，也更加能够容易简单理解；通过 onMessage, onEnd, onError 这几个专门对应用途的 callback 进行在对应触发时机进行回调。

onMessage 是在每一次 read 的回调当中进行处理，

当 read 方法读取全部流式数据时候 done 字段会返回 true，也就是 onEnd 的调用时机；

onError 就是在所有的相关异常情况都进行调用处理。

class FetchEventSource {
  eventController: any

  abortController: any

  constructor() {
    this.abortController = new AbortController() || null
  }

  // 这里使用的就是通过 onMessage, onEnd, onError 这几个专门的
  startFetchEvent(url, body, onMessage, onEnd, onError, headers = {}) {
    const fetchOptions = {
      method: 'POST',
      body: JSON.stringify(body),
      headers: Object.assign({}, {
        'Content-Type': 'application/json',
        authorization: `Bearer ${token}`,
      }),
      signal: this.abortController.signal,
    }

    // 发送 fetch 请求
    fetch(url, fetchOptions)
      .then((response: any) => {
        if (response && response.status && response.status !== 200) {
          const reader = response.body.getReader()

          // 开始处理读取 stream 流式数据
          reader.read().then((result) => {
            if (result.done) {
              return
            }

            const decoder = new TextDecoder()
            const receivedString = decoder.decode(result.value, { stream: true })

            try {
              onError(JSON.parse(receivedString))
            } catch (e) {
              onError(e)
            }
          })

          return response
        }

        const reader = response.body.getReader()
        reader.read()
          .then(function processResult(result) {
            if (result.done) {
              onEnd(result)

              return
            }

            const decoder = new TextDecoder()
            const receivedString = decoder.decode(result.value, { stream: true })
            onMessage(receivedString)

            return reader.read()
              .then(processResult)
          })

        return response
      })
      .catch(() => {
        this.eventController.abort()
        onError({ code: 201, message: '服务器异常' })
      })
  }

  stopFetchEvent() {
    if (this.eventController) {
      this.eventController.abort()
      this.eventController = null
    }
  }
}

callback 形式封装的调用例子：

const eventFetch = new FetchEventSource()

eventFetch.startFetchEvent('/api/xxx', params, (res) => {
  console.warn('onMessage: ', res)
}, (res) => {
  console.warn('onEnd: ', res)
}, (error) => {
  console.error('onError: '， error)
})

2. Generator 迭代器多步处理

Generator 迭代器这个知识因为并非这篇文章的重点这里就简单进行描述相关的基础用法

函数添加 * 标识符表示

函数内部使用 yield 关键字表示每一步的返回

调用迭代器函数后返回一个迭代器对象，并且该迭代器对象有一个 next 的函数

每次调用 next 则返回一个对象，对象有两个属性：

一个是 value，当迭代还没结束时候返回值为函数内部每一次 yield 的值，迭代结束时候返回 undefined

一个 done，表示是否还能进行迭代，当迭代还没结束时候返回 false，迭代结束时候返回 true

for await...of 创建一个循环，该循环遍历异步可迭代对象以及同步可迭代对象。

非常适用于需要按顺序对异步任务进行迭代遍历处理。

Generator MDN：developer.mozilla.org/zh-CN/docs/…

for-await...of MDN：developer.mozilla.org/zh-CN/docs/…

function* gen() {
  yield 1;
  yield 2;
  yield 3;
}

const g = gen(); // Generator { }
g.next(); // { value: 1, done: false }
g.next(); // { value: 2, done: false }
g.next(); // { value: 3, done: false }
g.next(); // { value: undefined, done: true }

使用 Generator 迭代器对前面的封装进行优化改造：

相比 callback 的形式，使用 Generator 并且配合通过 for await...of 的调用形式，能够更加直接清晰的使用同步的写法进行逻辑处理，能够降低回调地狱的风险。

onMessage 则是通过 Generator 迭代器的 yield 进行返回，在外面调用遍历则能获取到该分块的数据值；

当 read 方法读取全部流式数据时候 done 字段会返回 true，因此这时候不需要再调用 yield 即可，也就是前文的 onEnd callback，在外部调用这个封装的 Generator 迭代器方法则需要在遍历循环当中同样判断 done 字段是否为 true;

在方法内部抛出异常，在迭代器的外部调用则需要通过对异常进行捕获处理（而不再是通过 onError callback 处理）。

class FetchEventSource {
  abortController: any

  constructor() {
    this.abortController = new AbortController() || null
  }

  async* fetchEventGenerator(url, body, headers = {}) {
    const token: string = 'eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJmYW5nZ2VlayIsImF1ZCI6ImZhbmdnZWVrLmNsaWVudCIsImV4cCI6MTc2NjEyNTEyNCwianRpIjoiZ3pUSnhWcGNMNVlEWFVnSC1wWE0yUSIsImlhdCI6MTc2MzUzMzEyNCwibmJmIjoxNzYzNTMzMDA0LCJzdWIiOiIyIiwiZmFuZ2dlZWsiOiI1ZWYyYmM4NjczZDQ2YjIxODE4ZDliODUiLCJlbnYiOiJkZXYiLCJ0eXBlIjoxLCJ0ZWFtSWQiOiI1ZWYyYmM4NjczZDQ2YjIxODE4ZDliN2YiLCJ0ZWFtIjoiODE4ODAwMDEifQ.8aMWZ7i5s0qBHTXbtIw8wuEc1Ozw4_TewIQN-5Wv_5A'

    this.abortController = new AbortController()

    const fetchOptions = {
      method: 'POST',
      body: JSON.stringify(body),
      headers: Object.assign({}, {
        'Content-Type': 'application/json',
        authorization: `Bearer ${token}`,
      }, headers),
      signal: this.abortController.signal,
    }

    try {
      const response: any = await fetch(ENV_CONFIG.skmrHostPrefix + url, fetchOptions)

      if (response && response.status && response.status !== 200) {
        const reader = response.body.getReader()
        const result = await reader.read()
        const decoder = new TextDecoder()
        const receivedString = decoder.decode(result.value, { stream: true })

        try {
          throw JSON.parse(receivedString)
        } catch (e) {
          throw e
        }
      }

      const reader = response.body.getReader()
      const decoder = new TextDecoder()

      while (true) {
        const { done, value } = await reader.read()

        if (done) {
          break
        }

        yield decoder.decode(value, { stream: true })
      }
    } catch (error) {
      this.abortController.abort()
      throw error
    }
  }

  stopFetchEvent() {
    if (this.abortController) {
      this.abortController.abort()
    }
  }
}

调用例子：

这里因为取消了 onError callback 的形式调用参数，因此相关的错误处理则需要通过 try catch 进行处理。

而原本的 onMessage, onEnd 的 callback 则是通过 Generator 迭代遍历和 for wait...of 进行异步遍历处理。

await 返回的 res 则需要判断里面的 done 字段是否为 true 判断是否已经结束遍历了（也就是 onEnd 这个 callback，done 为 false 时候为 onMessage callback）。

const eventFetch = new FetchEventSource()

try {
  for await (const res of eventFetch.fetchEventGenerator('/api/xxx', params)) {
    const { done, value } = res || {}

    if (done) {
      console.warn('onEnd: ', value)
    } else {
      console.warn('onMessage: ', value)
    }
  }
} catch (error) {
  console.error('onError: '， error)
}

Flutter 客户端热更新实战

掘金前端

作者前端荣耀

2026年3月17日 20:03

本文将带你深入了解 Flutter 热更新的实现原理，并手把手教你使用 Shorebird 实现生产环境的热更新能力。

为什么需要热更新？

作为 Flutter 开发者，你是否遇到过这样的场景：

刚上线的版本发现了一个紧急 Bug，但应用商店审核需要 2-5 天
想快速验证一个小功能的效果，不想等待漫长的审核周期
需要在不发布新版本的情况下修复线上问题

传统应用发布流程：代码修改 → 构建 → 提交审核 → 等待审核 → 发布 → 用户更新，整个过程可能需要数天甚至数周。

而热更新可以将这个周期缩短到 几分钟：代码修改 → 推送补丁 → 用户下次启动生效。

Flutter 热更新的技术挑战

Flutter 采用 AOT（Ahead-Of-Time）编译，代码在发布时已经编译为机器码。这与 React Native 的 JS Bundle 模式不同，Flutter 无法直接像 RN 那样替换代码包。

但 Flutter 官方团队核心成员创立的 Shorebird 项目，通过巧妙的技术方案解决了这个问题：

Android：直接替换 Dart VM 中的编译代码，性能几乎无影响
iOS：使用自定义 Dart 解释器 + 智能链接器，仅对修改部分使用解释执行，约 98% 的代码仍以 AOT 模式全速运行

更重要的是，Shorebird 完全符合 Google Play 和 Apple App Store 的政策要求。

Shorebird 快速上手

第一步：安装 CLI 工具

# macOS / Linux
curl --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/shorebirdtech/install/main/install.sh -sSf | bash

# 验证安装
shorebird --version

安装完成后，运行诊断命令确保环境正常：

shorebird doctor

第二步：注册账号并登录

访问 console.shorebird.dev 注册账号
在终端登录：

shorebird login

这将打开浏览器完成认证，成功后会显示登录信息。

第三步：初始化项目

对于现有 Flutter 项目，只需执行：

cd your_flutter_project
shorebird init

这会在项目根目录生成 shorebird.yaml 配置文件：

# shorebird.yaml
app_id: ee322dc4-3dc2-4324-90a9-04c40a62ae76
# auto_update: false  # 取消注释可禁用自动更新

注意：app_id 可以公开，不是敏感信息。

第四步：创建 Release

在推送热更新之前，必须先创建一个基准版本：

# Android
shorebird release android

# iOS（需要 macOS）
shorebird release ios

命令执行后会看到类似输出：

✓ Building release (17.0s)
✓ Fetching apps (0.3s)
✓ Detecting release version (0.2s)

🚀 Ready to create a new release!

📱 App: my_app (51751336-6a7c-4972-b4ec-8fc1591fb2b3)
📦 Release Version: 1.0.0+1
🕹️ Platform: android (arm64, arm32, x86_64)

Would you like to continue? (y/N) Yes
✓ Published Release!

生成的文件位置：

Android: ./build/app/outputs/bundle/release/app-release.aab
iOS: ./build/ios/ipa/<app_name>.ipa

第五步：上传到应用商店

Android (Google Play) ：将生成的 .aab 文件上传到 Google Play Console。

iOS (App Store) ：

推荐使用以下方式之一上传：

# 方式一：使用 Transporter（推荐）
# 在 App Store 下载 Transporter 应用，然后拖入 .ipa 文件

# 方式二：使用 xcrun notarytool（命令行）
xcrun notarytool submit build/ios/ipa/app.ipa \
  --apple-id YOUR_APPLE_ID \
  --password YOUR_APP_SPECIFIC_PASSWORD \
  --team-id YOUR_TEAM_ID

# 方式三：使用 Xcode
# 打开 Xcode → Window → Organizer → 选择归档 → Distribute App

iOS 重要提示：在 Xcode 分发时，必须取消勾选 "Manage Version and Build Number"，否则会影响补丁功能。

第六步：推送热更新补丁

当发现 Bug 或需要更新时：

# 修改 Dart 代码后，推送补丁
shorebird patch android

# 推送到指定通道
shorebird patch android --track=staging

输出示例：

✓ Building patch (17.2s)
✓ Fetching apps (0.7s)
✓ Detecting release version (0.2s)

🚀 Ready to publish a new patch!

📱 App: my_app (...)
📦 Release Version: 1.0.0+1
📺 Channel: stable
🕹️ Platform: android [arm64 (135 B), arm32 (150 B), x86_64 (135 B)]

Would you like to continue? (y/N) Yes
✅ Published Patch!

恭喜！你的第一个热更新补丁已经推送成功。用户下次启动应用时会自动下载并应用更新。

进阶：手动控制更新流程

默认情况下，Shorebird 会在应用启动时自动检查并下载更新。但有时你需要更精细的控制，比如：

显示更新进度
用户确认后再应用更新
指定更新通道进行灰度测试

添加依赖

# pubspec.yaml
dependencies:
  shorebird_code_push: ^2.0.5

代码实现

import 'package:shorebird_code_push/shorebird_code_push.dart';

class MyApp extends StatefulWidget {
  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  final updater = ShorebirdUpdater();

  @override
  void initState() {
    super.initState();
    _checkCurrentPatch();
  }

  Future<void> _checkCurrentPatch() async {
    final patch = await updater.readCurrentPatch();
    print('当前补丁版本: ${patch?.number}');
  }

  /// 手动检查并安装更新
  Future<void> checkForUpdates() async {
    try {
      final status = await updater.checkForUpdate();
      
      if (status == UpdateStatus.outdated) {
        // 有新版本可用
        final shouldUpdate = await _showUpdateDialog();
        if (shouldUpdate) {
          await updater.update();
          _showSuccessDialog('更新成功，下次启动生效');
        }
      } else if (status == UpdateStatus.current) {
        _showInfoDialog('已是最新版本');
      }
    } on UpdateException catch (e) {
      _showErrorDialog('更新失败: $e');
    }
  }

  Future<bool> _showUpdateDialog() async {
    return await showDialog<bool>(
      context: context,
      builder: (context) => AlertDialog(
        title: Text('发现新版本'),
        content: Text('检测到有新的更新，是否立即下载？'),
        actions: [
          TextButton(
            child: Text('稍后'),
            onPressed: () => Navigator.pop(context, false),
          ),
          ElevatedButton(
            child: Text('立即更新'),
            onPressed: () => Navigator.pop(context, true),
          ),
        ],
      ),
    ) ?? false;
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('热更新示例')),
        body: Center(
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              ElevatedButton(
                onPressed: checkForUpdates,
                child: Text('检查更新'),
              ),
            ],
          ),
        ),
      ),
    );
  }
}

禁用自动更新

如果希望完全手动控制更新时机，在 shorebird.yaml 中禁用自动更新：

# shorebird.yaml
app_id: your-app-id
auto_update: false

灰度发布与测试

使用多通道进行灰度发布

Shorebird 支持多个发布通道，非常适合灰度测试：

# 创建测试通道补丁
shorebird patch android --track=beta

# 创建预发布通道补丁
shorebird patch android --track=staging

# 创建生产通道补丁（默认）
shorebird patch android --track=stable

代码中指定通道

// 使用预定义的 beta 通道（推荐）
final status = await updater.checkForUpdate(track: UpdateTrack.beta);
if (status == UpdateStatus.outdated) {
  await updater.update(track: UpdateTrack.beta);
}

// 或使用自定义通道名称
const customTrack = UpdateTrack('my-custom-track');
final status = await updater.checkForUpdate(track: customTrack);
if (status == UpdateStatus.outdated) {
  await updater.update(track: customTrack);
}

完整的灰度发布流程

# 1. 推送测试版本到 beta 通道
shorebird patch android --track=beta

# 2. 本地预览（可选）
shorebird preview --track beta --app-id YOUR_APP_ID --release-version 1.0.0+1

# 3. 测试通过后，提升到 stable 通道
# 方式一：在控制台操作 https://console.shorebird.dev
# 方式二：重新推送到 stable 通道
shorebird patch android --track=stable

CI/CD 集成

在自动化构建流程中集成 Shorebird，实现一键发布：

生成 CI Token

shorebird login:ci

输出：

A token was generated.

SHOREBIRD_TOKEN="eyJhbGciOiJSUzI1NiIsImtpZCI6IjEifQ..."

You can use this token in CI environments by setting the SHOREBIRD_TOKEN environment variable.

GitHub Actions 配置

# .github/workflows/release.yml
name: Release with Shorebird

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Java
        uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '17'
      
      - name: Setup Flutter
        uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.16.0'
      
      - name: Setup Shorebird
        uses: shorebirdtech/setup-shorebird@v1
        
      - name: Get dependencies
        run: flutter pub get
        
      - name: Release Android
        env:
          SHOREBIRD_TOKEN: ${{ secrets.SHOREBIRD_TOKEN }}
        run: |
          shorebird release android --force
          
      - name: Upload to Play Store
        uses: r0adkll/upload-google-play@v1
        with:
          serviceAccountJsonPlainText: ${{ secrets.PLAY_STORE_SERVICE_ACCOUNT }}
          packageName: com.example.app
          releaseFiles: build/app/outputs/bundle/release/app-release.aab
          track: internal

  patch:
    runs-on: ubuntu-latest
    needs: release
    if: github.event_name == 'push' && contains(github.ref, 'patch')
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Shorebird
        uses: shorebirdtech/setup-shorebird@v1
        
      - name: Push Patch
        env:
          SHOREBIRD_TOKEN: ${{ secrets.SHOREBIRD_TOKEN }}
        run: |
          shorebird patch android --force

常见问题与解决方案

Q1: 补丁推送后用户没有收到更新？

排查步骤：

# 1. 确认补丁已发布到正确通道
shorebird patches list

# 2. 检查应用版本号是否匹配
# 补丁只能应用于相同的 release 版本

# 3. 确认补丁发布到了 stable 通道（默认）
# 如果推送到 beta/staging，需要手动指定通道

注意：补丁在应用第二次启动时才会生效，这是设计如此。

Q2: iOS 补丁体积为什么比 Android 大很多？

这是正常现象：

平台	补丁大小	原因
Android	通常 KB 级别	直接替换编译代码
iOS	通常几百 KB	使用解释器模式，包含额外元数据

iOS 由于 App Store 政策限制，必须使用解释器执行更新代码，因此补丁体积较大。

Q3: 构建失败怎么办？

# 1. 检查环境
shorebird doctor

# 2. 清理缓存
shorebird cache clear

# 3. 重置 Shorebird 配置
rm -rf .shorebird
shorebird init

# 4. 检查 Flutter 版本
# Shorebird 需要使用其提供的 Flutter 版本
flutter --version

Q4: 哪些场景不能使用热更新？

场景	能否热更新	说明
修改 Dart 代码	✅ 支持	最常见的使用场景
修改 UI 布局	✅ 支持	纯 Dart 实现
修改业务逻辑	✅ 支持	纯 Dart 实现
修改原生代码（Java/Kotlin/Swift/ObjC）	❌ 不支持	需要发布新版本
新增权限	❌ 不支持	需要商店审核
更新原生依赖版本	❌ 不支持	需要发布新版本
改变应用主要功能	❌ 违规	违反商店政策

Q5: 如何追踪补丁版本用于数据分析？

void trackPatchVersion() async {
  final patchNumber = await ShorebirdUpdater().readCurrentPatch();
  
  // 上报到分析平台
  analytics.logEvent('app_launch', {
    'app_version': '1.0.0',
    'patch_number': patchNumber?.number ?? 0,
  });
}

Q6: 补丁会改变应用版本号吗？

不会。补丁是在相同版本号下的更新，不会修改 pubspec.yaml 中的版本号。

这可能导致分析平台无法区分热更新，建议通过补丁号进行追踪（见上一条）。

最佳实践

1. 合理规划版本发布策略

┌─────────────────────────────────────────────────────────────┐
│                   推荐发布策略                                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Release (商店版本)：                                        │
│  - 主要功能更新                                              │
│  - 原生代码变更                                              │
│  - 频率：每 2-4 周                                           │
│                                                             │
│  Patch (热更新)：                                            │
│  - 紧急 Bug 修复                                             │
│  - UI/文案调整                                               │
│  - 业务逻辑优化                                              │
│  - 频率：按需，随时推送                                       │
│                                                             │
└─────────────────────────────────────────────────────────────┘

2. 使用语义化版本号

# pubspec.yaml
version: 1.0.0+1

# 版本格式：major.minor.patch+buildNumber
# - major: 重大功能变更
# - minor: 功能迭代
# - patch: Bug 修复
# - buildNumber: 构建号（每次构建递增）

3. 建立 Staging 测试流程

# 开发 → Staging 测试 → 生产发布

# 1. 推送到 staging
shorebird patch android --track=staging

# 2. 测试人员验证
shorebird preview --track staging

# 3. 验证通过后提升到 stable
# 在控制台操作或使用命令

4. 为用户提供清晰的更新提示

// ✅ 好的做法
class UpdatePrompt {
  void showUpdateNotice(String version) {
    showDialog(
      context: context,
      builder: (context) => AlertDialog(
        title: Text('发现新版本'),
        content: Column(
          mainAxisSize: MainAxisSize.min,
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            Text('版本 $version 包含以下更新：'),
            SizedBox(height: 8),
            Text('• 修复了登录页闪退问题'),
            Text('• 优化了首页加载速度'),
            Text('• 更新了用户协议'),
          ],
        ),
        actions: [
          TextButton(
            child: Text('稍后'),
            onPressed: () => Navigator.pop(context),
          ),
          ElevatedButton(
            child: Text('立即更新'),
            onPressed: applyUpdate,
          ),
        ],
      ),
    );
  }
}

// ❌ 不好的做法：静默更新且不告知用户
// 这可能导致用户困惑，且违反某些地区的用户知情权法规

定价与方案选择

Shorebird 提供灵活的定价方案，适合不同规模的团队：

计划	月费	月安装量	适用场景
Free	$0	5,000	个人项目、小型 MVP
Pro	$20	50,000	中小型应用
Business	$400	1,000,000	大型应用、企业项目
Enterprise	定制	定制	特殊需求

对于大多数中小团队，Pro 计划 已足够使用。如果月安装量超出配额，按 $1/2,500 次计算超额费用。

总结

Shorebird 为 Flutter 开发者提供了成熟、合规、易用的热更新解决方案。通过本文的实战指南，你应该已经掌握了：

核心原理：理解 Shorebird 如何在 Android/iOS 上实现代码热更新
基础使用：从安装到推送第一个补丁的完整流程
进阶控制：手动管理更新、灰度发布、多通道测试
CI/CD 集成：自动化构建发布流程
故障排查：常见问题的解决方案

热更新是一把双刃剑，合理使用可以大幅提升迭代效率，但也要注意：

不能滥用热更新绕过商店审核
遵守平台政策，不改变应用主要功能
做好版本追踪和数据分析

参考资源

软键盘常见问题(二)

掘金前端

作者小小小小宇

2026年3月17日 19:52

前端 H5 软键盘常见问题及解决方案

1. 键盘弹起导致页面布局错乱 / 整体上推

问题：iOS Safari 中键盘弹起时，页面（body 或容器）会被整体上推，收起后页面可能无法回弹，出现底部留白。

解决方案：监听 visualViewport API 动态调整布局

// 利用 visualViewport 获取真实可视区域
function initVisualViewport() {
  if (!window.visualViewport) return;

  function onResize() {
    const { height } = window.visualViewport;
    document.documentElement.style.setProperty('--vh', `${height * 0.01}px`);
  }

  window.visualViewport.addEventListener('resize', onResize);
  window.visualViewport.addEventListener('scroll', onResize);
  onResize();
}

initVisualViewport();

/* 根元素使用动态视口单位 */
:root {
  --vh: 1vh;
}

.container {
  height: 100vh;
  height: calc(var(--vh, 1vh) * 100);
  /* 兼容不支持 visualViewport 的环境 */
}

也可以使用 window.visualViewport.offsetTop 判断是否被键盘遮挡，并手动 scrollTo。

2. iOS 键盘收起后页面不回弹（留白问题）

问题：iOS 12+ Safari 中，输入框失焦后页面底部出现空白区域，滚动条位置异常。

解决方案一：滚动到顶部 / blur 时强制滚动

function fixIOSBlank() {
  const inputs = document.querySelectorAll('input, textarea');

  inputs.forEach(input => {
    input.addEventListener('blur', () => {
      // 延迟执行，等键盘收起动画结束
      setTimeout(() => {
        // 方案 A：滚动到顶部
        window.scrollTo(0, 0);
        document.body.scrollTop = 0;
        document.documentElement.scrollTop = 0;

        // 方案 B（可选）：滚动到当前焦点元素
        // const active = document.activeElement;
        // if (active && active.scrollIntoView) {
        //   active.scrollIntoView({ behavior: 'smooth' });
        // }
      }, 100);
    });
  });
}

解决方案二：使用 scrollIntoView 配合 preventScroll

document.querySelectorAll('input, textarea').forEach(el => {
  el.addEventListener('focus', () => {
    // 让输入框滚入可视区，但不自动调整页面
    el.scrollIntoView({ block: 'center', behavior: 'smooth' });
  });
});

3. `fixed` 定位元素在键盘弹起时失效

问题：键盘弹起后，position: fixed 的元素（如底部工具栏）表现异常：

iOS 上 fixed 会变成 absolute，随页面滚动
Android 上 fixed 元素被键盘遮挡或被推到键盘上方

解决方案：放弃 fixed，改用 absolute + visualViewport

<div class="page-wrapper">
 div class="content">...</div>
 div class="bottom-bar">底部栏</div>
</div>

.page-wrapper {
  position: relative;
  width: 100%;
  min-height: 100vh;
  min-height: calc(var(--vh, 1vh) * 100);
}

.bottom-bar {
  position: absolute;
  bottom: 0;
  left: 0;
  width: 100%;
}

// 实时更新 bottom-bar 位置
if (window.visualViewport) {
  window.visualViewport.addEventListener('resize', () => {
    const offset = window.innerHeight - window.visualViewport.height;
    document.querySelector('.bottom-bar').style.bottom = `${offset}px`;
  });
}

4. Android `windowSoftInputMode` 的影响

问题：在 Android WebView 或混合 App 中，键盘弹起行为受 windowSoftInputMode 控制，H5 侧无法直接干预但需要适配。

模式	行为
`adjustResize`	Activity 大小调整，`visualViewport` 会变化（推荐）
`adjustPan`	页面平移，H5 布局不变
`adjustNothing`	不做任何调整，输入框可能被遮挡

H5 侧适配方案：无论原生配置哪种模式，都用 visualViewport 做 fallback：

function getKeyboardHeight() {
  if (window.visualViewport) {
    return window.innerHeight - window.visualViewport.height;
  }
  return 0;
}

function isKeyboardOpen() {
  return getKeyboardHeight() > 100; // 阈值
}

5. 输入框被键盘遮挡（不自动滚动）

问题：某些 Android 浏览器和 WKWebView 中，键盘弹起时输入框不会自动滚入可视区域。

解决方案：scrollIntoView + 延迟

function ensureVisible(input) {
  if (!input) return;

  // iOS 需要延迟等待键盘动画
  const delay = /iPhone|iPad|iPod/.test(navigator.userAgent) ? 300 : 100;

  setTimeout(() => {
    input.scrollIntoView({
      block: 'center',
      behavior: 'smooth'
    });
  }, delay);
}

// 绑定到所有输入框
document.querySelectorAll('input, textarea').forEach(el => {
  el.addEventListener('focus', () => ensureVisible(el));
});

6. iOS `input` 框获得焦点时页面缩放

问题：iOS 上input>的font-size` 小于 16px 时，页面会自动缩放。

解决方案：强制设置 font-size >= 16px

input, textarea, select {
  font-size: 16px !important;
}

如果设计稿字号必须小于 16px，可以通过 transform: scale() 缩小容器来视觉欺骗：

.input-wrapper {
  transform: scale(0.875); /* 14px 视觉效果 */
  transform-origin: left center;
}

.input-wrapper input {
  font-size: 16px; /* 实际 16px，不会被缩放 */
}

7. 第三方键盘（搜狗 / 百度）导致的兼容问题

问题：第三方输入法键盘高度与系统键盘不一致，且可能多次触发 resize 事件。

解决方案：防抖 + 动态计算

function createKeyboardHandler(callback) {
  let lastHeight = 0;
  let timer = null;

  return function handler() {
    clearTimeout(timer);
    timer = setTimeout(() => {
      if (!window.visualViewport) return;

      const keyboardHeight = window.innerHeight - window.visualViewport.height;

      // 只有高度变化超过阈值才视为有效变化（过滤第三方键盘抖动）
      if (Math.abs(keyboardHeight - lastHeight) > 50) {
        lastHeight = keyboardHeight;
        callback({
          isOpen: keyboardHeight > 100,
          height: keyboardHeight
        });
      }
    }, 150); // 防抖 150ms
  };
}

// 使用
const onKeyboardChange = createKeyboardHandler(({ isOpen, height }) => {
  console.log('键盘状态:', isOpen ? '打开' : '关闭', '高度:', height);
  document.querySelector('.bottom-bar').style.transform =
    isOpen ? `translateY(-${height}px)` : 'translateY(0)';
});

window.visualViewport?.addEventListener('resize', onKeyboardChange);

8. iOS WebKit 的 `interactive-widget=resizes-content` 方案（现代方案）

iOS 16+ / Safari 16+ 支持 CSS interactive-widget 属性：

html {
  /* 让键盘弹出时缩小视口而非覆盖内容 */
  interactive-widget: resizes-content;
}

/* 或者 */
html {
  /* 让页面在键盘上方滚动 */
  interactive-widget: content-overlays;
}

配合 visualViewport 使用效果最佳。

9. Chat 场景 —— 输入框 + 底部栏随键盘上移

这是最常见的复杂场景，一个完整的封装方案：

<div class="chat-page">
 div class="chat-messages" id="chatMessages">
    <!-- 消息列表 -->
  </div>
 div class="chat-input-bar" id="chatInputBar">
   input type="text" id="chatInput" placeholder="输入消息..." />
   button id="sendBtn">发送</button>
  </div>
</div>

html {
  interactive-widget: resizes-content; /* iOS 16+ 优化 */
}

:root {
  --keyboard-height: 0px;
  --vh: 1vh;
}

.chat-page {
  display: flex;
  flex-direction: column;
  height: 100vh;
  height: calc(var(--vh, 1vh) * 100);
  overflow: hidden;
}

.chat-messages {
  flex: 1;
  overflow-y: auto;
  padding: 16px;
  padding-bottom: calc(var(--keyboard-height) + 60px);
  /* 留出底部输入栏 + 键盘的空间 */
}

.chat-input-bar {
  position: fixed;
  bottom: var(--keyboard-height);
  left: 0;
  right: 0;
  display: flex;
  padding: 8px 16px;
  background: #fff;
  border-top: 1px solid #eee;
  transition: bottom 0.25s ease;
}

.chat-input-bar input {
  flex: 1;
  height: 40px;
  font-size: 16px; /* 防止 iOS 缩放 */
  border: 1px solid #ddd;
  border-radius: 20px;
  padding: 0 16px;
}

class KeyboardManager {
  constructor() {
    this.keyboardHeight = 0;
    this.isOpen = false;
    this.init();
  }

  init() {
    // 方案 1：visualViewport（现代浏览器）
    if (window.visualViewport) {
      window.visualViewport.addEventListener('resize', () => this.onViewportResize());
      window.visualViewport.addEventListener('scroll', () => this.onViewportResize());
      this.updateVH();
    }

    // 方案 2：原生交互（WebView 场景）
    this.setupNativeBridge();

    // 方案 3：focus/blur fallback
    this.setupFocusFallback();
  }

  updateVH() {
    const vh = window.visualViewport.height * 0.01;
    document.documentElement.style.setProperty('--vh', `${vh}px`);
  }

  onViewportResize() {
    this.updateVH();

    const height = window.innerHeight - window.visualViewport.height;
    const isOpen = height > 100;

    if (height !== this.keyboardHeight || isOpen !== this.isOpen) {
      this.keyboardHeight = height;
      this.isOpen = isOpen;

      document.documentElement.style.setProperty(
        '--keyboard-height',
        `${isOpen ? height : 0}px`
      );

      this.onKeyboardChange?.(isOpen, height);
    }
  }

  setupNativeBridge() {
    // 与原生 WebView 通信获取键盘高度（适用于混合 App）
    // Android: 通过 JSBridge 接收 keyboardWillShow / keyboardWillHide
    window.onKeyboardShow = (height) => {
      this.keyboardHeight = height;
      this.isOpen = true;
      document.documentElement.style.setProperty('--keyboard-height', `${height}px`);
    };

    window.onKeyboardHide = () => {
      this.keyboardHeight = 0;
      this.isOpen = false;
      document.documentElement.style.setProperty('--keyboard-height', '0px');
    };
  }

  setupFocusFallback() {
    // visualViewport 不可用时的降级方案
    document.addEventListener('focusin', (e) => {
      if (e.target.matches('input, textarea')) {
        setTimeout(() => {
          e.target.scrollIntoView({ block: 'center', behavior: 'smooth' });
        }, 300);
      }
    });

    document.addEventListener('focusout', () => {
      // iOS 键盘收起后页面回弹
      setTimeout(() => {
        window.scrollTo(0, Math.max(0, document.body.scrollTop));
      }, 100);
    });
  }
}

// 使用
const kb = new KeyboardManager();

kb.onKeyboardChange = (isOpen, height) => {
  // 键盘状态变化时的业务逻辑
  const messages = document.getElementById('chatMessages');

  if (isOpen) {
    // 键盘弹起，滚动消息列表到底部
    setTimeout(() => {
      messages.scrollTop = messages.scrollHeight;
    }, 250);
  }
};

总结：问题速查表

问题	核心方案	关键 API
页面上推 / 留白	动态视口单位 `--vh`	`visualViewport.height`
`fixed` 失效	改用 `absolute` + 动态 bottom	`visualViewport`
输入框被遮挡	`scrollIntoView` + 延迟	Element API
iOS 页面缩放	`font-size >= 16px`	CSS
键盘高度获取不准	防抖 + 阈值过滤	`visualViewport`
第三方键盘抖动	防抖 + 变化量阈值	JS debounce
Android WebView	原生桥接 + `visualViewport` 兜底	JSBridge
iOS 16+ 优化	`interactive-widget` CSS 属性	CSS

核心思路：不依赖 window.innerHeight 的变化，而是使用 visualViewport API 获取真实可视区域，结合 CSS 变量动态更新布局，同时在旧浏览器做 focus/blur 事件的降级处理。

软键盘常见问题

掘金前端

作者小小小小宇

2026年3月17日 19:43

H5 移动端开发中，软键盘（Soft Keyboard）问题是“最为棘手”的兼容性痛点之一。由于 iOS (Safari/WKWebView) 和 Android (Chrome/System WebView) 对软键盘的处理机制不同，会导致各种布局错乱、遮挡、不回弹等问题。

以下是开发中常见的五大核心问题及其解决方案、原理分析和详细代码。

1. 输入框被软键盘遮挡 (Input Covered)

问题描述： 当用户点击页面下方的输入框时，软键盘弹出，但输入框被键盘覆盖，用户看不到自己输入的内容。

原因分析：

Android: 软键盘弹出时，会改变 window.innerHeight，页面可视区域变小，通常会自动将聚焦元素滚动到可视区，但也可能失败。
iOS: 软键盘是“浮层”，不改变 window.innerHeight，但会改变 visualViewport。系统会尝试推起页面，但在某些复杂布局（如 fixed 布局）中会失效。

解决方案： 使用 Element.scrollIntoView() 或 scrollIntoViewIfNeeded() 方法。在输入框获取焦点（focus）并延时一小段时间后（等待键盘完全弹出），强制将输入框滚动到可视区域。

详细代码：

// 通用处理函数
function handleInputFocus(event) {
  const target = event.target;
  
  // 延时是为了等待键盘完全弹出（iOS和Android弹出动画时间不同，通常300-500ms足够）
  setTimeout(() => {
    // 检查是否支持 scrollIntoViewOptions
    if ('scrollIntoView' in target) {
      target.scrollIntoView({
        behavior: 'smooth', // 平滑滚动
        block: 'center',    // 将输入框置于屏幕中间，体验最好
        inline: 'nearest'
      });
    } else {
      // 降级处理
      target.scrollIntoView(false);
    }
  }, 400); 
}

// 监听所有输入框的 focus 事件
const inputs = document.querySelectorAll('input, textarea');
inputs.forEach(input => {
  input.addEventListener('focus', handleInputFocus);
});

2. iOS 键盘收起后页面底部留白/不回弹 (The "Scroll Back" Bug)

问题描述： 在 iOS（特别是微信内置浏览器）中，当软键盘收起后，页面被推上去的部分没有自动回弹下来，导致页面下方出现大片空白（灰色或白色背景），且按钮错位，点击无效。

原因分析： iOS 12+ 的 Webview 在键盘收起时，页面视图（Layout Viewport）没有触发重绘或恢复滚动位置。

解决方案： 在输入框失去焦点（blur）时，强制让页面“抖动”一下或重置滚动位置。

详细代码：

// 全局监听 focusout (冒泡阶段，或者用 blur 捕获)
document.body.addEventListener('focusout', () => {
  // 判断是否是 iOS 设备
  const isIOS = /iPad|iPhone|iPod/.test(navigator.userAgent);
  
  if (isIOS) {
    // 延时执行，确保键盘已经完全收起
    setTimeout(() => {
      // 方法1: 获取当前滚动高度并微调
      const scrollHeight = document.documentElement.scrollTop || document.body.scrollTop || 0;
      window.scrollTo(0, Math.max(scrollHeight - 1, 0));
      
      // 方法2 (更暴力但有效): 滚动到顶部再滚回来 (如果用户体验允许)
      // window.scrollTo(0, 0); 
    }, 100);
  }
});

3. Android 底部固定按钮被键盘顶起 (Fixed Footer Floating)

问题描述： 页面底部有一个 position: fixed; bottom: 0; 的按钮（如“提交”按钮）。在 Android 上，键盘弹起会把视口高度压缩，导致这个按钮“骑”在键盘上方，遮挡内容或布局难看。iOS 通常依然吸附在键盘背面（不可见），表现较好，但也可能出现。

原因分析： Android 软键盘弹出时，浏览器窗口高度 (window.innerHeight) 发生了物理变化，fixed 元素依然相对于窗口底部定位，所以被顶上去了。

解决方案： 监听 resize 事件。如果窗口高度变小了（说明键盘弹出了），手动隐藏底部按钮；键盘收起时再显示。

详细代码：

const originalHeight = window.innerHeight; // 记录页面初始高度
const submitBtn = document.getElementById('submit-btn'); // 你的底部按钮

// 仅针对 Android 处理，iOS 也可以加，但通常不需要
const isAndroid = /Android/.test(navigator.userAgent);

if (isAndroid) {
  window.addEventListener('resize', () => {
    const resizeHeight = window.innerHeight;
    
    // 如果当前高度比原始高度小 20% 以上，说明键盘弹起了
    if (resizeHeight < originalHeight * 0.8) {
      // 隐藏底部按钮，或者将其定位改为 absolute / static
      submitBtn.style.display = 'none';
    } else {
      // 恢复显示
      submitBtn.style.display = 'block';
    }
  });
}

CSS 优化方案 (推荐): 使用 CSS 媒体查询 aspect-ratio 或 min-height 来辅助隐藏，但 JS 方案最稳。或者，使用 flex 布局，中间内容区 flex: 1; overflow-y: auto;，这样通常能避免 Fixed 元素乱飞。

4. 无法触发“搜索”/“前往”按键 (Custom Enter Key)

问题描述： 用户在输入框输入完内容后，键盘右下角显示的是“换行”或“Return”，而不是预期的“搜索”、“完成”或“前往”。

原因分析： 如果不将 input 包裹在 form 标签中，或没有设置正确的属性，浏览器默认认为是普通文本输入。

解决方案：

将 input 放在 <form> 标签内。
设置 <form action="javascript:void(0);"> 防止页面刷新。
设置 input 的 type="search" (或其他类型)。
使用 enterkeyhint 属性（现代浏览器支持）。

详细代码：

<!-- HTML 结构 -->
<form action="javascript:void(0);" id="searchForm">
  <!-- 
    inputmode: 提示键盘类型 
    enterkeyhint: 定制回车键文案 (enter, done, go, next, previous, search, send)
  -->
  <input 
    type="search" 
    placeholder="请输入搜索内容" 
    inputmode="search" 
    enterkeyhint="search"
    id="searchInput"
  >
</form>

<script>
  const searchInput = document.getElementById('searchInput');
  
  // 监听回车键事件
  searchInput.addEventListener('keyup', (e) => {
    // keyCode 13 是回车键
    if (e.key === 'Enter' || e.keyCode === 13) {
      // 失去焦点，收起键盘
      searchInput.blur(); 
      // 执行搜索逻辑
      doSearch(searchInput.value);
    }
  });
  
  function doSearch(val) {
    console.log('Searching for:', val);
  }
</script>

5. 唤起错误的键盘类型 (Wrong Keyboard Layout)

问题描述： 用户需要输入验证码（纯数字），但弹出了全键盘，用户需要手动切换，体验差。

原因分析： type 属性设置不当。

解决方案： 组合使用 type、pattern 和 inputmode 属性。

详细代码：

<!-- 1. 纯数字键盘 (验证码场景) -->
<!-- pattern="[0-9]*" 在 iOS 上至关重要，能唤起九宫格数字键盘 -->
<input type="text" inputmode="numeric" pattern="[0-9]*" placeholder="请输入验证码">

<!-- 2. 身份证 (需要数字 + X) -->
<!-- iOS 没有完美的身份证键盘，通常用普通键盘或自定义键盘 -->
<input type="text" placeholder="身份证号">

<!-- 3. 电话号码 (唤起拨号盘) -->
<input type="tel" placeholder="请输入手机号">

<!-- 4. 邮箱 -->
<input type="email" placeholder="输入邮箱">

<!-- 5. 小数点数字 -->
<input type="text" inputmode="decimal" placeholder="输入金额">

总结与最佳实践

布局策略： 尽量少用 position: fixed 布局底部按钮。推荐使用 Flex 布局：

body { display: flex; flex-direction: column; height: 100vh; }
.content { flex: 1; overflow-y: auto; } /* 中间滚动 */
.footer { flex-shrink: 0; } /* 底部固定，但属于文档流 */

视口单位： 谨慎使用 100vh。在移动端，100vh 包含了地址栏的高度，可能导致滚动条问题。推荐使用 window.innerHeight 计算高度并赋值给 CSS 变量，或者使用新的 CSS 单位 dvh (Dynamic Viewport Height，但需注意兼容性)。
第三方库： 如果项目非常复杂，可以考虑使用 Element UI Mobile 或 Vant 等成熟的 UI 库，它们内部已经处理了很多此类兼容性问题。

处理 H5 软键盘问题没有“银弹”，通常需要结合 UserAgent 判断（iOS vs Android）来应用不同的补丁代码。

富文本编辑器知识体系(三)

掘金前端

作者小小小小宇

2026年3月17日 19:20

接续：项目结构 + 自动保存 + 内容展示 + 完整面试答题模板

十一、完整项目结构参考（续）

src/
├── editor/
│   ├── interface.js                 # 编辑器统一接口定义
│   ├── factory.js                   # 工厂函数
│   │
│   ├── adapters/                    # 适配器层
│   │   ├── tiptap-adapter.js
│   │   ├── wangeditor-adapter.js
│   │   ├── slate-adapter.js
│   │   └── quill-adapter.js
│   │
│   ├── extensions/                  # 自定义扩展
│   │   ├── mention/
│   │   │   ├── MentionNode.js       # @提及节点
│   │   │   ├── MentionList.vue      # 候选人列表弹窗
│   │   │   └── suggestion.js        # 触发逻辑
│   │   │
│   │   ├── image/
│   │   │   ├── ImageNode.js         # 图片节点（支持拖拽缩放）
│   │   │   ├── ImageUploadPlugin.js # 粘贴/拖拽上传
│   │   │   └── ImageResizer.vue     # 缩放手柄组件
│   │   │
│   │   ├── video/
│   │   │   ├── VideoNode.js
│   │   │   └── VideoEmbed.vue
│   │   │
│   │   ├── code-block/
│   │   │   ├── CodeBlockNode.js     # 代码块（+语法高亮）
│   │   │   └── LanguageSelect.vue
│   │   │
│   │   ├── table/
│   │   │   ├── TableNode.js
│   │   │   └── TableMenu.vue        # 表格右键菜单
│   │   │
│   │   └── slash-command/
│   │       ├── SlashCommand.js      # / 命令面板
│   │       └── CommandList.vue
│   │
│   ├── plugins/                     # 通用插件
│   │   ├── auto-save.js             # 自动保存
│   │   ├── word-count.js            # 字数统计
│   │   ├── paste-handler.js         # 粘贴处理
│   │   ├── drag-handle.js           # 块级拖拽
│   │   ├── placeholder.js           # 占位符
│   │   └── read-time.js             # 阅读时间估算
│   │
│   ├── toolbar/                     # 工具栏
│   │   ├── Toolbar.vue              # 固定工具栏
│   │   ├── BubbleMenu.vue           # 浮动工具栏（选中文字时出现）
│   │   ├── FloatingMenu.vue         # 空行菜单（新行时出现）
│   │   └── toolbar-config.js        # 工具栏配置
│   │
│   └── collab/                      # 协同编辑
│       ├── CollabProvider.js         # Yjs Provider 封装
│       ├── CursorPlugin.js          # 协同光标
│       ├── AwarenessWidget.vue       # 在线用户显示
│       └── collab-server.js          # 服务端
│
├── components/
│   ├── RichEditor.vue               # 通用编辑器组件（业务组件直接使用）
│   ├── ReadonlyRenderer.vue         # 只读展示组件
│   └── EditorSkeleton.vue           # 加载骨架屏
│
├── services/
│   ├── upload.js                    # 上传服务
│   └── article.js                   # 文章 CRUD 服务
│
├── utils/
│   ├── sanitize.js                  # XSS 过滤
│   ├── html-to-markdown.js          # HTML ↔ Markdown 转换
│   └── delta-diff.js                # 内容差异对比
│
└── styles/
    ├── editor-base.scss             # 编辑器基础样式
    ├── editor-content.scss          # 内容区域样式（编辑和展示共用）
    └── editor-theme.scss            # 主题变量

十二、自动保存完整实现

// plugins/auto-save.js

/**
 * 自动保存插件
 *
 * 功能：
 * 1. 内容变化后自动保存（防抖）
 * 2. 定时保存（兜底）
 * 3. 离开页面前保存
 * 4. 保存失败重试
 * 5. 本地草稿箱（localStorage 兜底）
 * 6. 增量保存（只传变化部分）
 * 7. 保存状态指示
 */

export class AutoSavePlugin {
  constructor(options = {}) {
    this.options = {
      // 防抖延迟（内容变化后多久触发保存）
      debounceDelay: 3000,
      // 定时保存间隔（兜底）
      intervalDelay: 30000,
      // 保存函数（由业务传入）
      saveFn: null,
      // 文档唯一标识
      docId: null,
      // 最大重试次数
      maxRetry: 3,
      // 重试延迟
      retryDelay: 2000,
      // 本地缓存 key 前缀
      cachePrefix: 'editor_draft_',
      // 状态变化回调
      onStatusChange: null,
      ...options,
    };

    // 内部状态
    this.state = {
      status: 'saved', // saved | saving | unsaved | error
      lastSavedAt: null,
      lastContent: null,
      retryCount: 0,
      dirty: false,
    };

    this.debounceTimer = null;
    this.intervalTimer = null;
    this.destroyed = false;
  }

  /**
   * 初始化（在编辑器挂载后调用）
   */
  init(getContent) {
    this.getContent = getContent;
    this.state.lastContent = getContent();

    // 启动定时保存
    this.intervalTimer = setInterval(() => {
      if (this.state.dirty && !this.destroyed) {
        this.save();
      }
    }, this.options.intervalDelay);

    // 页面离开前保存
    this._beforeUnload = (e) => {
      if (this.state.dirty) {
        // 同步保存到 localStorage
        this.saveToLocal();
        // 提示用户
        e.preventDefault();
        e.returnValue = '您有未保存的更改，确定要离开吗？';
        return e.returnValue;
      }
    };
    window.addEventListener('beforeunload', this._beforeUnload);

    // 页面可见性变化时保存（切tab时）
    this._visibilityChange = () => {
      if (document.hidden && this.state.dirty) {
        this.save();
      }
    };
    document.addEventListener('visibilitychange', this._visibilityChange);

    // 检查是否有未恢复的本地草稿
    this.checkLocalDraft();

    return this;
  }

  /**
   * 内容变化时调用（由编辑器的onChange触发）
   */
  onChange() {
    this.state.dirty = true;
    this.updateStatus('unsaved');

    // 防抖保存
    clearTimeout(this.debounceTimer);
    this.debounceTimer = setTimeout(() => {
      this.save();
    }, this.options.debounceDelay);

    // 每次变化都保存到localStorage（同步，快速）
    this.saveToLocal();
  }

  /**
   * 执行保存
   */
  async save() {
    if (this.destroyed) return;
    if (!this.state.dirty) return;
    if (this.state.status === 'saving') return; // 避免重复保存

    const content = this.getContent();

    // 内容没有实际变化
    if (content === this.state.lastContent) {
      this.state.dirty = false;
      this.updateStatus('saved');
      return;
    }

    this.updateStatus('saving');

    try {
      if (typeof this.options.saveFn !== 'function') {
        throw new Error('saveFn is not configured');
      }

      await this.options.saveFn({
        docId: this.options.docId,
        content,
        // 增量信息（可选，后端根据这个做diff存储）
        previousContent: this.state.lastContent,
        timestamp: Date.now(),
      });

      // 保存成功
      this.state.lastContent = content;
      this.state.dirty = false;
      this.state.retryCount = 0;
      this.state.lastSavedAt = new Date();
      this.updateStatus('saved');

      // 清除本地草稿（服务端已保存）
      this.clearLocalDraft();

      console.log(`[AutoSave] 保存成功 ${this.state.lastSavedAt.toLocaleTimeString()}`);
    } catch (error) {
      console.error('[AutoSave] 保存失败:', error);

      // 重试逻辑
      if (this.state.retryCount < this.options.maxRetry) {
        this.state.retryCount++;
        this.updateStatus('error');
        console.log(
          `[AutoSave] ${this.options.retryDelay}ms 后重试 (${this.state.retryCount}/${this.options.maxRetry})`
        );
        setTimeout(() => this.save(), this.options.retryDelay * this.state.retryCount);
      } else {
        this.updateStatus('error');
        // 确保本地有备份
        this.saveToLocal();
        console.error('[AutoSave] 达到最大重试次数，内容已保存到本地');
      }
    }
  }

  /**
   * 保存到 localStorage（兜底方案）
   */
  saveToLocal() {
    try {
      const key = this.options.cachePrefix + this.options.docId;
      const data = {
        content: this.getContent(),
        timestamp: Date.now(),
        docId: this.options.docId,
      };
      localStorage.setItem(key, JSON.stringify(data));
    } catch (e) {
      // localStorage 可能满了
      console.warn('[AutoSave] localStorage 保存失败:', e.message);
      // 尝试清理旧草稿
      this.cleanOldDrafts();
    }
  }

  /**
   * 检查本地草稿
   */
  checkLocalDraft() {
    try {
      const key = this.options.cachePrefix + this.options.docId;
      const stored = localStorage.getItem(key);
      if (!stored) return null;

      const data = JSON.parse(stored);
      const age = Date.now() - data.timestamp;

      // 超过7天的草稿忽略
      if (age > 7 * 24 * 60 * 60 * 1000) {
        localStorage.removeItem(key);
        return null;
      }

      return data;
    } catch {
      return null;
    }
  }

  /**
   * 恢复本地草稿
   */
  recoverLocalDraft() {
    const draft = this.checkLocalDraft();
    if (draft) {
      return draft.content;
    }
    return null;
  }

  /**
   * 清除本地草稿
   */
  clearLocalDraft() {
    const key = this.options.cachePrefix + this.options.docId;
    localStorage.removeItem(key);
  }

  /**
   * 清理旧草稿（localStorage 空间不足时）
   */
  cleanOldDrafts() {
    const prefix = this.options.cachePrefix;
    const keys = [];

    for (let i = 0; i < localStorage.length; i++) {
      const key = localStorage.key(i);
      if (key.startsWith(prefix)) {
        try {
          const data = JSON.parse(localStorage.getItem(key));
          keys.push({ key, timestamp: data.timestamp });
        } catch {
          localStorage.removeItem(key); // 损坏的数据直接删
        }
      }
    }

    // 按时间排序，删除最旧的一半
    keys.sort((a, b) => a.timestamp - b.timestamp);
    const deleteCount = Math.ceil(keys.length / 2);
    keys.slice(0, deleteCount).forEach(({ key }) => {
      localStorage.removeItem(key);
    });
  }

  /**
   * 更新状态
   */
  updateStatus(status) {
    this.state.status = status;
    this.options.onStatusChange?.({
      status,
      lastSavedAt: this.state.lastSavedAt,
      retryCount: this.state.retryCount,
    });
  }

  /**
   * 手动保存（用户点击保存按钮）
   */
  async forceSave() {
    this.state.dirty = true;
    clearTimeout(this.debounceTimer);
    await this.save();
  }

  /**
   * 获取当前状态
   */
  getStatus() {
    return { ...this.state };
  }

  /**
   * 销毁
   */
  destroy() {
    this.destroyed = true;

    // 最后保存一次
    if (this.state.dirty) {
      this.saveToLocal();
    }

    clearTimeout(this.debounceTimer);
    clearInterval(this.intervalTimer);
    window.removeEventListener('beforeunload', this._beforeUnload);
    document.removeEventListener('visibilitychange', this._visibilityChange);
  }
}

在 Vue 组件中集成：

<template>
  <div class="editor-page">
    <!-- 保存状态指示器 -->
    <div class="save-status">
      <span v-if="saveStatus === 'saved'" class="status-saved">
        ✓ 已保存
        <small v-if="lastSavedAt">{{ formatTime(lastSavedAt) }}</small>
      </span>
      <span v-else-if="saveStatus === 'saving'" class="status-saving">
        <i class="loading-icon" /> 保存中...
      </span>
      <span v-else-if="saveStatus === 'unsaved'" class="status-unsaved">
        ● 未保存
      </span>
      <span v-else-if="saveStatus === 'error'" class="status-error">
        ✗ 保存失败
        <button @click="retrySave">重试</button>
      </span>
    </div>

    <!-- 草稿恢复提示 -->
    <div v-if="hasDraft" class="draft-banner">
      <span>检测到未保存的草稿（{{ formatTime(draftTime) }}）</span>
      <button @click="recoverDraft">恢复草稿</button>
      <button @click="dismissDraft">忽略</button>
    </div>

    <!-- 编辑器 -->
    <RichEditor
      ref="editor"
      v-model="content"
      @change="onContentChange"
    />

    <!-- 手动保存按钮 -->
    <div class="actions">
      <button @click="handleSave" :disabled="saveStatus === 'saving'">
        {{ saveStatus === 'saving' ? '保存中...' : '保存' }}
      </button>
      <span class="shortcut-hint">Ctrl+S</span>
    </div>
  </div>
</template>

<script>
import RichEditor from '@/components/RichEditor.vue';
import { AutoSavePlugin } from '@/editor/plugins/auto-save';
import { saveArticle } from '@/services/article';

export default {
  components: { RichEditor },

  props: {
    articleId: { type: String, required: true },
  },

  data() {
    return {
      content: '',
      saveStatus: 'saved',
      lastSavedAt: null,
      hasDraft: false,
      draftTime: null,
      autoSave: null,
    };
  },

  async mounted() {
    // 1. 加载文章内容
    await this.loadArticle();

    // 2. 初始化自动保存
    this.autoSave = new AutoSavePlugin({
      docId: this.articleId,
      debounceDelay: 3000,
      intervalDelay: 30000,
      maxRetry: 3,
      saveFn: async ({ docId, content }) => {
        await saveArticle(docId, { content });
      },
      onStatusChange: ({ status, lastSavedAt }) => {
        this.saveStatus = status;
        this.lastSavedAt = lastSavedAt;
      },
    }).init(() => this.content);

    // 3. 检查本地草稿
    const draft = this.autoSave.checkLocalDraft();
    if (draft && draft.timestamp > this.serverTimestamp) {
      this.hasDraft = true;
      this.draftTime = new Date(draft.timestamp);
    }

    // 4. Ctrl+S 快捷键
    this._keydown = (e) => {
      if ((e.ctrlKey || e.metaKey) && e.key === 's') {
        e.preventDefault();
        this.handleSave();
      }
    };
    document.addEventListener('keydown', this._keydown);
  },

  methods: {
    async loadArticle() {
      const res = await fetch(`/api/articles/${this.articleId}`);
      const data = await res.json();
      this.content = data.content;
      this.serverTimestamp = data.updatedAt;
    },

    onContentChange() {
      this.autoSave?.onChange();
    },

    async handleSave() {
      await this.autoSave?.forceSave();
    },

    retrySave() {
      this.autoSave.state.retryCount = 0;
      this.autoSave.save();
    },

    recoverDraft() {
      const draftContent = this.autoSave.recoverLocalDraft();
      if (draftContent) {
        this.content = draftContent;
        this.hasDraft = false;
      }
    },

    dismissDraft() {
      this.autoSave.clearLocalDraft();
      this.hasDraft = false;
    },

    formatTime(date) {
      if (!date) return '';
      const d = new Date(date);
      return `${d.getHours()}:${String(d.getMinutes()).padStart(2, '0')}`;
    },
  },

  beforeDestroy() {
    this.autoSave?.destroy();
    document.removeEventListener('keydown', this._keydown);
  },
};
</script>

<style scoped>
.save-status {
  display: flex;
  align-items: center;
  gap: 8px;
  padding: 8px 16px;
  font-size: 13px;
}
.status-saved { color: #52c41a; }
.status-saving { color: #1890ff; }
.status-unsaved { color: #faad14; }
.status-error { color: #ff4d4f; }

.loading-icon {
  display: inline-block;
  width: 12px;
  height: 12px;
  border: 2px solid #1890ff;
  border-top-color: transparent;
  border-radius: 50%;
  animation: spin 0.8s linear infinite;
}
@keyframes spin { to { transform: rotate(360deg); } }

.draft-banner {
  display: flex;
  align-items: center;
  gap: 12px;
  padding: 10px 16px;
  background: #fffbe6;
  border: 1px solid #ffe58f;
  border-radius: 4px;
  margin: 8px 16px;
  font-size: 14px;
}
</style>

十三、内容安全展示组件

<!-- components/ReadonlyRenderer.vue -->
<!-- 用于文章详情页、评论展示等，安全渲染 HTML -->

<template>
  <div
    class="rich-content-renderer"
    :class="[`theme-${theme}`, { 'content-compact': compact }]"
    v-html="sanitizedHtml"
  />
</template>

<script>
import { sanitizeForDisplay } from '@/utils/sanitize';

export default {
  name: 'ReadonlyRenderer',

  props: {
    html: { type: String, default: '' },
    theme: {
      type: String,
      default: 'default', // default | github | notion
    },
    compact: { type: Boolean, default: false },
    // 是否允许图片点击放大
    imagePreview: { type: Boolean, default: true },
    // 是否自动添加锚点
    autoAnchor: { type: Boolean, default: true },
  },

  computed: {
    sanitizedHtml() {
      let html = sanitizeForDisplay(this.html);

      // 处理标题锚点
      if (this.autoAnchor) {
        html = this.addHeadingAnchors(html);
      }

      // 外链处理
      html = this.processLinks(html);

      // 代码块处理
      html = this.processCodeBlocks(html);

      return html;
    },
  },

  mounted() {
    if (this.imagePreview) {
      this.setupImagePreview();
    }
    // 代码块添加复制按钮
    this.setupCodeCopy();
  },

  updated() {
    if (this.imagePreview) {
      this.setupImagePreview();
    }
    this.setupCodeCopy();
  },

  methods: {
    /**
     * 标题添加锚点
     */
    addHeadingAnchors(html) {
      const div = document.createElement('div');
      div.innerHTML = html;
      const headings = div.querySelectorAll('h1,h2,h3,h4,h5,h6');

      headings.forEach((heading, index) => {
        const text = heading.textContent.trim();
        const id = `heading-${index}-${encodeURIComponent(text)}`;
        heading.id = id;
        heading.style.position = 'relative';

        // 添加锚点链接
        const anchor = document.createElement('a');
        anchor.href = `#${id}`;
        anchor.className = 'heading-anchor';
        anchor.textContent = '#';
        anchor.setAttribute('aria-hidden', 'true');
        heading.prepend(anchor);
      });

      return div.innerHTML;
    },

    /**
     * 外链添加安全属性 + 图标
     */
    processLinks(html) {
      const div = document.createElement('div');
      div.innerHTML = html;
      const links = div.querySelectorAll('a[href]');

      links.forEach((link) => {
        const href = link.getAttribute('href');

        // 外链
        if (href && (href.startsWith('http') || href.startsWith('//'))) {
          link.setAttribute('target', '_blank');
          link.setAttribute('rel', 'noopener noreferrer nofollow');
          link.classList.add('external-link');
        }
      });

      return div.innerHTML;
    },

    /**
     * 代码块添加语言标签
     */
    processCodeBlocks(html) {
      const div = document.createElement('div');
      div.innerHTML = html;
      const codeBlocks = div.querySelectorAll('pre > code');

      codeBlocks.forEach((code) => {
        const pre = code.parentElement;
        pre.classList.add('code-block-wrapper');

        // 从 class 中提取语言
        const langClass = Array.from(code.classList).find((c) => c.startsWith('language-'));
        const lang = langClass ? langClass.replace('language-', '') : 'text';

        // 添加语言标签
        const langLabel = document.createElement('span');
        langLabel.className = 'code-lang-label';
        langLabel.textContent = lang;
        pre.insertBefore(langLabel, code);
      });

      return div.innerHTML;
    },

    /**
     * 图片点击预览
     */
    setupImagePreview() {
      const images = this.$el.querySelectorAll('img');
      images.forEach((img) => {
        img.style.cursor = 'zoom-in';
        img.removeEventListener('click', this._imageClickHandler);
        img.addEventListener('click', this._imageClickHandler = () => {
          this.showImagePreview(img.src);
        });
      });
    },

    /**
     * 图片预览弹窗（简化版）
     */
    showImagePreview(src) {
      const overlay = document.createElement('div');
      overlay.style.cssText = `
        position:fixed; top:0; left:0; right:0; bottom:0;
        background:rgba(0,0,0,0.8); display:flex;
        align-items:center; justify-content:center;
        z-index:9999; cursor:zoom-out;
      `;

      const img = document.createElement('img');
      img.src = src;
      img.style.cssText = `
        max-width:90vw; max-height:90vh;
        object-fit:contain; border-radius:4px;
      `;

      overlay.appendChild(img);
      overlay.addEventListener('click', () => overlay.remove());
      document.addEventListener('keydown', function handler(e) {
        if (e.key === 'Escape') {
          overlay.remove();
          document.removeEventListener('keydown', handler);
        }
      });

      document.body.appendChild(overlay);
    },

    /**
     * 代码块复制按钮
     */
    setupCodeCopy() {
      const codeBlocks = this.$el.querySelectorAll('pre');
      codeBlocks.forEach((pre) => {
        if (pre.querySelector('.code-copy-btn')) return; // 已添加

        const btn = document.createElement('button');
        btn.className = 'code-copy-btn';
        btn.textContent = '复制';
        btn.addEventListener('click', async () => {
          const code = pre.querySelector('code');
          const text = code ? code.textContent : pre.textContent;

          try {
            await navigator.clipboard.writeText(text);
            btn.textContent = '已复制 ✓';
            setTimeout(() => {
              btn.textContent = '复制';
            }, 2000);
          } catch {
            // 降级方案
            const textarea = document.createElement('textarea');
            textarea.value = text;
            textarea.style.cssText = 'position:fixed;opacity:0;';
            document.body.appendChild(textarea);
            textarea.select();
            document.execCommand('copy');
            document.body.removeChild(textarea);
            btn.textContent = '已复制 ✓';
            setTimeout(() => {
              btn.textContent = '复制';
            }, 2000);
          }
        });

        pre.style.position = 'relative';
        pre.appendChild(btn);
      });
    },
  },

  beforeDestroy() {
    // 清理事件监听
    const images = this.$el.querySelectorAll('img');
    images.forEach((img) => {
      img.removeEventListener('click', this._imageClickHandler);
    });
  },
};
</script>

<style lang="scss">
.rich-content-renderer {
  font-size: 16px;
  line-height: 1.8;
  color: #333;
  word-wrap: break-word;
  overflow-wrap: break-word;

  // ===== 标题 =====
  h1, h2, h3, h4, h5, h6 {
    margin-top: 1.5em;
    margin-bottom: 0.5em;
    font-weight: 600;
    line-height: 1.4;

    &:first-child { margin-top: 0; }
  }
  h1 { font-size: 1.75em; }
  h2 { font-size: 1.5em; border-bottom: 1px solid #eee; padding-bottom: 0.3em; }
  h3 { font-size: 1.25em; }

  // 标题锚点
  .heading-anchor {
    position: absolute;
    left: -1.2em;
    color: #1890ff;
    text-decoration: none;
    opacity: 0;
    transition: opacity 0.2s;
    font-weight: normal;
  }
  h1:hover .heading-anchor,
  h2:hover .heading-anchor,
  h3:hover .heading-anchor {
    opacity: 1;
  }

  // ===== 段落 =====
  p {
    margin: 0.8em 0;
    &:first-child { margin-top: 0; }
    &:last-child { margin-bottom: 0; }
  }

  // ===== 列表 =====
  ul, ol {
    padding-left: 1.5em;
    margin: 0.5em 0;
  }
  li {
    margin: 0.25em 0;
  }

  // ===== 引用 =====
  blockquote {
    margin: 1em 0;
    padding: 0.5em 1em;
    border-left: 4px solid #1890ff;
    background: #f6f8fa;
    color: #555;
    border-radius: 0 4px 4px 0;

    p { margin: 0.3em 0; }
  }

  // ===== 代码 =====
  code {
    padding: 0.15em 0.4em;
    background: #f0f0f0;
    border-radius: 3px;
    font-family: 'Fira Code', 'Consolas', monospace;
    font-size: 0.9em;
    color: #d56161;
  }
  pre {
    margin: 1em 0;
    padding: 16px;
    background: #282c34;
    border-radius: 8px;
    overflow-x: auto;
    position: relative;

    code {
      padding: 0;
      background: none;
      color: #abb2bf;
      font-size: 14px;
      line-height: 1.6;
      border-radius: 0;
    }

    // 语言标签
    .code-lang-label {
      position: absolute;
      top: 8px;
      right: 60px;
      font-size: 12px;
      color: #636d83;
      text-transform: uppercase;
      user-select: none;
    }

    // 复制按钮
    .code-copy-btn {
      position: absolute;
      top: 8px;
      right: 8px;
      padding: 2px 10px;
      font-size: 12px;
      color: #abb2bf;
      background: rgba(255, 255, 255, 0.1);
      border: 1px solid rgba(255, 255, 255, 0.15);
      border-radius: 4px;
      cursor: pointer;
      opacity: 0;
      transition: opacity 0.2s, background 0.2s;

      &:hover {
        background: rgba(255, 255, 255, 0.2);
      }
    }

    &:hover .code-copy-btn {
      opacity: 1;
    }
  }

  // ===== 图片 =====
  img {
    max-width: 100%;
    height: auto;
    border-radius: 4px;
    margin: 0.5em 0;
    transition: transform 0.2s;

    &:hover {
      transform: scale(1.01);
      box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
    }
  }

  // ===== 表格 =====
  table {
    width: 100%;
    border-collapse: collapse;
    margin: 1em 0;
    font-size: 14px;

    th, td {
      border: 1px solid #ddd;
      padding: 10px 14px;
      text-align: left;
    }

    th {
      background: #f6f8fa;
      font-weight: 600;
      color: #333;
    }

    tr:nth-child(even) {
      background: #fafbfc;
    }

    tr:hover {
      background: #f0f7ff;
    }
  }

  // ===== 链接 =====
  a {
    color: #1890ff;
    text-decoration: none;
    border-bottom: 1px solid transparent;
    transition: border-color 0.2s;

    &:hover {
      border-bottom-color: #1890ff;
    }

    // 外链图标
    &.external-link::after {
      content: '↗';
      font-size: 0.75em;
      margin-left: 2px;
      vertical-align: super;
    }
  }

  // ===== 分割线 =====
  hr {
    border: none;
    border-top: 1px solid #e8e8e8;
    margin: 2em 0;
  }

  // ===== 提及 =====
  .mention-tag {
    color: #1890ff;
    background: #e6f7ff;
    padding: 1px 4px;
    border-radius: 2px;
    cursor: pointer;

    &:hover {
      background: #bae7ff;
    }
  }

  // ===== 删除线 =====
  del, s {
    color: #999;
    text-decoration: line-through;
  }

  // ===== 标记高亮 =====
  mark {
    background: #ffffb8;
    padding: 1px 2px;
    border-radius: 2px;
  }

  // ===== 紧凑模式（用于评论等场景） =====
  &.content-compact {
    font-size: 14px;
    line-height: 1.6;

    h1, h2, h3 { font-size: 1.15em; margin-top: 0.8em; }
    p { margin: 0.4em 0; }
    blockquote { padding: 0.3em 0.8em; margin: 0.5em 0; }
    pre { padding: 12px; margin: 0.5em 0; }
    img { max-height: 400px; object-fit: contain; }
  }

  // ===== GitHub 主题 =====
  &.theme-github {
    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, sans-serif;
    color: #24292f;

    h2 { border-bottom: 1px solid #d0d7de; }
    blockquote { border-left-color: #d0d7de; color: #656d76; }
    code { background: rgba(175, 184, 193, 0.2); color: inherit; }
  }

  // ===== Notion 主题 =====
  &.theme-notion {
    font-family: 'Segoe UI', Helvetica, sans-serif;
    color: rgb(55, 53, 47);

    h1, h2, h3 { font-weight: 700; }
    blockquote {
      border-left-color: #000;
      background: transparent;
      font-size: 1.1em;
    }
    code { background: rgba(135, 131, 120, 0.15); color: #eb5757; }
  }
}
</style>

十四、目录提取组件

<!-- components/TableOfContents.vue -->
<!-- 从编辑器内容中提取标题，生成可点击的目录 -->

<template>
  <nav class="toc" v-if="headings.length > 0">
    <h4 class="toc-title">目录</h4>
    <ul class="toc-list">
      <li
        v-for="(heading, index) in headings"
        :key="index"
        :class="[
          `toc-level-${heading.level}`,
          { active: activeId === heading.id }
        ]"
      >
        <a
          :href="`#${heading.id}`"
          @click.prevent="scrollToHeading(heading.id)"
          :title="heading.text"
        >
          {{ heading.text }}
        </a>
      </li>
    </ul>
  </nav>
</template>

<script>
export default {
  name: 'TableOfContents',

  props: {
    html: { type: String, default: '' },
    // 监听哪个容器的滚动
    scrollContainer: { type: String, default: null },
    // 偏移量（固定头部高度）
    offsetTop: { type: Number, default: 80 },
  },

  data() {
    return {
      headings: [],
      activeId: '',
      observer: null,
    };
  },

  watch: {
    html: {
      immediate: true,
      handler(val) {
        this.$nextTick(() => {
          this.extractHeadings(val);
          this.setupScrollSpy();
        });
      },
    },
  },

  methods: {
    /**
     * 从 HTML 中提取标题
     */
    extractHeadings(html) {
      const div = document.createElement('div');
      div.innerHTML = html;
      const elements = div.querySelectorAll('h1, h2, h3, h4');

      this.headings = Array.from(elements).map((el, index) => {
        const text = el.textContent.trim();
        const level = parseInt(el.tagName[1]);
        const id = el.id || `heading-${index}-${encodeURIComponent(text)}`;

        return { id, text, level };
      });
    },

    /**
     * 滚动到指定标题
     */
    scrollToHeading(id) {
      const el = document.getElementById(id);
      if (!el) return;

      const top = el.getBoundingClientRect().top + window.pageYOffset - this.offsetTop;
      window.scrollTo({ top, behavior: 'smooth' });
      this.activeId = id;

      // 更新 URL hash（不触发跳转）
      history.replaceState(null, '', `#${id}`);
    },

    /**
     * 滚动监听：高亮当前所在标题
     */
    setupScrollSpy() {
      // 清理旧的 observer
      this.observer?.disconnect();

      this.observer = new IntersectionObserver(
        (entries) => {
          // 找到第一个进入视口的标题
          for (const entry of entries) {
            if (entry.isIntersecting) {
              this.activeId = entry.target.id;
              break;
            }
          }
        },
        {
          rootMargin: `-${this.offsetTop}px 0px -70% 0px`,
        }
      );

      // 观察所有标题元素
      this.$nextTick(() => {
        this.headings.forEach(({ id }) => {
          const el = document.getElementById(id);
          if (el) {
            this.observer.observe(el);
          }
        });
      });
    },
  },

  beforeDestroy() {
    this.observer?.disconnect();
  },
};
</script>

<style scoped>
.toc {
  position: sticky;
  top: 80px;
  max-height: calc(100vh - 120px);
  overflow-y: auto;
  padding: 16px;
  border-left: 2px solid #f0f0f0;
}

.toc-title {
  font-size: 14px;
  color: #999;
  margin: 0 0 12px 0;
  text-transform: uppercase;
  letter-spacing: 1px;
}

.toc-list {
  list-style: none;
  padding: 0;
  margin: 0;
}

.toc-list li {
  margin: 4px 0;
  transition: all 0.2s;
}

.toc-list li a {
  display: block;
  padding: 4px 8px;
  font-size: 13px;
  color: #666;
  text-decoration: none;
  border-radius: 4px;
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
  transition: all 0.2s;
}

.toc-list li a:hover {
  color: #1890ff;
  background: #f0f7ff;
}

/* 缩进层级 */
.toc-level-1 { padding-left: 0; }
.toc-level-1 a { font-weight: 600; font-size: 14px; }
.toc-level-2 { padding-left: 12px; }
.toc-level-3 { padding-left: 24px; }
.toc-level-3 a { font-size: 12px; }
.toc-level-4 { padding-left: 36px; }
.toc-level-4 a { font-size: 12px; color: #999; }

/* 高亮当前标题 */
.active a {
  color: #1890ff !important;
  font-weight: 600;
  background: #e6f7ff;
  border-left: 3px solid #1890ff;
}
</style>

十五、面试完整答题模板

模板：当被问到"你们项目的富文本编辑器是怎么做的？"

============================================
答题框架（3-5分钟完整回答）
============================================

第一部分：背景和选型（30秒）
──────────────────────────
"我们项目是一个内容管理平台/知识库/博客系统，
核心场景是文章编辑，需要支持基础排版、图片上传、
@提及、代码块等功能。

选型上我们对比了几个方案：
- wangEditor：开箱即用但扩展性不足
- Quill：体积小但大文档性能一般
- Tiptap：基于ProseMirror，扩展性最好
- Slate.js：灵活但上手成本高

最终选了 Tiptap/wangEditor（根据实际情况），
主要考虑：Vue生态适配好、社区活跃、满足功能需求。"


第二部分：架构设计（1分钟）
──────────────────────────
"架构上我做了几个关键设计：

1）适配器模式封装：
定义了统一的编辑器接口（getHTML/setContent/insertImage等），
底层通过适配器对接具体编辑器。
这样如果将来需要换编辑器，只需要新增适配器，
业务组件完全不用改。

2）插件化扩展：
图片上传、@提及、自动保存都做成独立插件，
按需加载，职责分离。

3）工具栏配置化：
工具栏通过配置数组驱动，不同场景（文章编辑/评论/邮件）
传不同配置即可复用同一个编辑器组件。"


第三部分：核心难点（1-2分钟，挑2-3个讲）
──────────────────────────

难点1：图片上传
"图片支持工具栏按钮、粘贴、拖拽三种方式上传。
流程是：前端压缩 → 上传服务（支持进度展示）→ 返回CDN URL → 插入编辑器。
做了并发控制（最多3张同时传）、失败重试（3次）、大图压缩（>1920px缩放）。"

难点2：XSS 安全
"富文本的XSS防护我们做了纵深防御：
- 编辑器层：粘贴时剥离危险标签
- 提交前：DOMPurify 白名单过滤
- 服务端：二次过滤（最关键，不信任前端）
- 展示层：CSP头 + img域名白名单
主要防的攻击向量包括script注入、事件属性注入、
javascript:协议注入等。"

难点3：自动保存
"做了防抖保存（3秒）+ 定时兜底（30秒）+ 
beforeunload 保存 + localStorage 草稿箱。
保存失败自动重试3次，重试失败保证本地有备份。
还做了草稿恢复提示——如果检测到本地有比服务端更新的草稿，
会提示用户选择恢复或忽略。"

难点4（如果问到协同编辑）：
"协同编辑用的 Yjs + WebSocket。
Yjs 是 CRDT 方案，每个字符有全局唯一ID，
通过 leftOrigin/rightOrigin 定位，天然支持冲突合并。
相比 OT 方案不需要中心服务器排序，支持离线后合并。
在线用户的光标位置通过 Awareness 协议同步，
做了颜色区分和名字标签展示。"


第四部分：性能优化（30秒）
──────────────────────────
"性能方面做了几个优化：
- 编辑器组件异步加载（减少首屏体积200KB+）
- onChange 防抖（避免高频序列化）
- 图片懒加载（IntersectionObserver）
- 自动保存用增量比较，内容没变不发请求
- 历史记录限制100步 + 连续输入合并"


第五部分：收尾（15秒）
──────────────────────────
"整体这套方案上线后运行稳定，
支撑了日均 XX 篇文章的编辑需求，
用户反馈编辑体验比之前好很多。
如果要继续优化的话，我会考虑：
- Markdown 快捷输入（输入##自动转标题）
- 更完善的表格编辑
- 离线编辑能力"

十六、最后总结

┌────────────────────────────────────────────────────────┐
│              富文本编辑器知识体系总览                     │
├────────────────────────────────────────────────────────┤
│                                                        │
│  理论基础                                              │
│  ├── contentEditable 原理与局限                        │
│  ├── 文档模型设计（树形 vs 扁平）                      │
│  ├── 选区（Selection/Range）管理                       │
│  ├── 中文输入法（IME Composition）处理                 │
│  └── 操作变换（OT）与 CRDT 冲突解决                   │
│                                                        │
│  工程实践                                              │
│  ├── 编辑器选型（场景驱动决策）                        │
│  ├── 适配器模式封装（可替换底层实现）                  │
│  ├── 插件化架构（图片/提及/@/自动保存）                │
│  ├── 图片上传（压缩/并发控制/粘贴拖拽）               │
│  ├── XSS 纵深防御（前端+后端+CSP）                    │
│  ├── 自动保存（防抖+定时+本地兜底+恢复）              │
│  ├── 安全展示（过滤HTML+代码复制+图片预览）           │
│  └── 性能优化（懒加载/防抖/Worker序列化）             │
│                                                        │
│  面试要点                                              │
│  ├── 能说清楚选型理由和取舍                            │
│  ├── 能画出整体架构图                                  │
│  ├── 能深入 2-3 个技术难点                             │
│  ├── 有性能优化意识                                    │
│  └── 有安全意识（XSS不是说说而已）                    │
│                                                        │
│  加分项                                                │
│  ├── 了解 ProseMirror 文档模型和 Transaction 机制     │
│  ├── 了解 CRDT/OT 原理                                │
│  ├── 了解 Lexical 的双缓冲架构                        │
│  ├── 做过协同编辑                                      │
│  └── 做过编辑器自定义扩展/插件                         │
│                                                        │
└────────────────────────────────────────────────────────┘

以上是完整的富文本编辑器技术方案，涵盖了：

模块	内容
选型	5大编辑器横向对比 + 决策树
架构	适配器模式 + 统一接口 + 工厂函数
封装	Vue通用组件 + v-model双向绑定
图片上传	压缩/并发/粘贴拖拽/进度/重试
XSS安全	DOMPurify白名单 + 后端二次过滤 + CSP
自动保存	防抖+定时+离开保存+本地草稿+恢复提示
内容展示	安全渲染+代码复制+图片预览+目录提取
性能优化	懒加载/防抖/Worker/虚拟滚动
面试	9道高频题 + 完整答题模板

富文本编辑器知识体系(二)

掘金前端

作者小小小小宇

2026年3月17日 19:17

五、通用封装架构：适配器模式(接上篇)

当项目中可能更换编辑器时，使用适配器模式隔离底层实现：

┌─────────────────────────────────────────────────────┐
│                  业务组件层                           │
│                                                     │
│     <RichEditor v-model="content" mode="full" />    │
│                                                     │
├─────────────────────────────────────────────────────┤
│               统一接口层 (Adapter)                   │
│                                                     │
│   interface IEditor {                               │
│     getHTML(): string                               │
│     getJSON(): object                               │
│     getText(): string                               │
│     setContent(content): void                       │
│     clear(): void                                   │
│     focus(): void                                   │
│     destroy(): void                                 │
│     on(event, handler): void                        │
│   }                                                 │
│                                                     │
├──────────┬──────────┬──────────┬────────────────────┤
│ WangEditor│  Tiptap  │  Quill   │  Slate Adapter    │
│ Adapter   │ Adapter  │ Adapter  │                    │
└──────────┴──────────┴──────────┴────────────────────┘

5.1 统一接口定义

// editor/interface.js

/**
 * 编辑器统一接口
 * @typedef {Object} EditorAdapter
 */
export class EditorAdapter {
  /**
   * @param {HTMLElement} container - 挂载容器
   * @param {Object} options - 配置选项
   */
  constructor(container, options = {}) {
    this.container = container;
    this.options = options;
    this.listeners = new Map();
    this.instance = null;
  }

  /** 初始化编辑器 */
  init() { throw new Error('Must implement init()'); }

  /** 获取 HTML */
  getHTML() { throw new Error('Must implement getHTML()'); }

  /** 获取纯文本 */
  getText() { throw new Error('Must implement getText()'); }

  /** 获取 JSON 结构 */
  getJSON() { throw new Error('Must implement getJSON()'); }

  /** 设置内容 */
  setContent(content) { throw new Error('Must implement setContent()'); }

  /** 清空 */
  clear() { throw new Error('Must implement clear()'); }

  /** 聚焦 */
  focus() { throw new Error('Must implement focus()'); }

  /** 设置是否可编辑 */
  setEditable(editable) { throw new Error('Must implement setEditable()'); }

  /** 销毁 */
  destroy() { throw new Error('Must implement destroy()'); }

  /** 插入图片 */
  insertImage(url, alt) { throw new Error('Must implement insertImage()'); }

  /** 注册事件 */
  on(event, handler) {
    if (!this.listeners.has(event)) {
      this.listeners.set(event, []);
    }
    this.listeners.get(event).push(handler);
  }

  /** 触发事件 */
  emit(event, ...args) {
    const handlers = this.listeners.get(event) || [];
    handlers.forEach((handler) => handler(...args));
  }

  /** 移除事件 */
  off(event, handler) {
    if (!handler) {
      this.listeners.delete(event);
      return;
    }
    const handlers = this.listeners.get(event) || [];
    this.listeners.set(event, handlers.filter((h) => h !== handler));
  }
}

5.2 各适配器实现

// editor/adapters/tiptap-adapter.js

import { Editor } from '@tiptap/core';
import StarterKit from '@tiptap/starter-kit';
import Image from '@tiptap/extension-image';
import Link from '@tiptap/extension-link';
import Placeholder from '@tiptap/extension-placeholder';
import { EditorAdapter } from '../interface';

export class TiptapAdapter extends EditorAdapter {
  init() {
    this.instance = new Editor({
      element: this.container,
      content: this.options.initialContent || '',
      editable: this.options.editable !== false,
      extensions: [
        StarterKit,
        Image.configure({ inline: true }),
        Link.configure({ openOnClick: false }),
        Placeholder.configure({
          placeholder: this.options.placeholder || '请输入内容...',
        }),
        ...(this.options.extensions || []),
      ],
      onUpdate: ({ editor }) => {
        this.emit('change', {
          html: editor.getHTML(),
          text: editor.getText(),
          json: editor.getJSON(),
        });
      },
      onFocus: () => this.emit('focus'),
      onBlur: () => this.emit('blur'),
    });

    return this;
  }

  getHTML() {
    return this.instance.getHTML();
  }

  getText() {
    return this.instance.getText();
  }

  getJSON() {
    return this.instance.getJSON();
  }

  setContent(content) {
    if (typeof content === 'string') {
      this.instance.commands.setContent(content);
    } else {
      this.instance.commands.setContent(content); // JSON
    }
  }

  clear() {
    this.instance.commands.clearContent();
  }

  focus() {
    this.instance.commands.focus();
  }

  setEditable(editable) {
    this.instance.setEditable(editable);
  }

  insertImage(url, alt = '') {
    this.instance.chain().focus().setImage({ src: url, alt }).run();
  }

  destroy() {
    this.instance?.destroy();
    this.listeners.clear();
  }
}

// editor/adapters/wangeditor-adapter.js

import { createEditor, createToolbar } from '@wangeditor/editor';
import { EditorAdapter } from '../interface';

export class WangEditorAdapter extends EditorAdapter {
  init() {
    // wangEditor 需要两个容器
    const toolbarContainer = document.createElement('div');
    const editorContainer = document.createElement('div');
    editorContainer.style.minHeight = '300px';

    this.container.appendChild(toolbarContainer);
    this.container.appendChild(editorContainer);

    this.instance = createEditor({
      selector: editorContainer,
      html: this.options.initialContent || '<p><br></p>',
      config: {
        placeholder: this.options.placeholder || '请输入内容...',
        readOnly: this.options.editable === false,
        onChange: (editor) => {
          this.emit('change', {
            html: editor.getHtml(),
            text: editor.getText(),
            json: editor.children,
          });
        },
        onFocus: () => this.emit('focus'),
        onBlur: () => this.emit('blur'),
        MENU_CONF: this.options.menuConf || {},
      },
    });

    this.toolbar = createToolbar({
      editor: this.instance,
      selector: toolbarContainer,
      config: this.options.toolbarConfig || {},
    });

    return this;
  }

  getHTML() {
    return this.instance.getHtml();
  }

  getText() {
    return this.instance.getText();
  }

  getJSON() {
    return this.instance.children;
  }

  setContent(content) {
    if (typeof content === 'string') {
      this.instance.setHtml(content);
    }
  }

  clear() {
    this.instance.clear();
  }

  focus() {
    this.instance.focus();
  }

  setEditable(editable) {
    if (editable) {
      this.instance.enable();
    } else {
      this.instance.disable();
    }
  }

  insertImage(url, alt = '') {
    this.instance.dangerouslyInsertNode({
      type: 'image',
      src: url,
      alt,
      children: [{ text: '' }],
    });
  }

  destroy() {
    this.instance?.destroy();
    this.toolbar?.destroy?.();
    this.listeners.clear();
  }
}

5.3 工厂函数 + Vue 通用组件

// editor/factory.js

import { TiptapAdapter } from './adapters/tiptap-adapter';
import { WangEditorAdapter } from './adapters/wangeditor-adapter';

const ADAPTERS = {
  tiptap: TiptapAdapter,
  wangeditor: WangEditorAdapter,
  // quill: QuillAdapter,
  // slate: SlateAdapter,
};

/**
 * 创建编辑器实例
 * @param {'tiptap' | 'wangeditor' | 'quill'} type
 * @param {HTMLElement} container
 * @param {Object} options
 * @returns {EditorAdapter}
 */
export function createEditorAdapter(type, container, options = {}) {
  const AdapterClass = ADAPTERS[type];
  if (!AdapterClass) {
    throw new Error(`Unsupported editor type: ${type}. Available: ${Object.keys(ADAPTERS).join(', ')}`);
  }
  return new AdapterClass(container, options).init();
}

<!-- components/RichEditor.vue —— 通用富文本组件 -->
<template>
  <div class="rich-editor-wrapper">
    <div ref="editorContainer" class="editor-container"></div>
  </div>
</template>

<script>
import { createEditorAdapter } from '@/editor/factory';

export default {
  name: 'RichEditor',

  props: {
    // 编辑器类型：可通过配置文件全局切换
    type: {
      type: String,
      default: process.env.VUE_APP_EDITOR_TYPE || 'tiptap',
      validator: (v) => ['tiptap', 'wangeditor', 'quill'].includes(v),
    },
    value: { type: String, default: '' },
    placeholder: { type: String, default: '请输入内容...' },
    editable: { type: Boolean, default: true },
    options: { type: Object, default: () => ({}) },
  },

  data() {
    return {
      adapter: null,
      internalUpdate: false,
    };
  },
  mounted() {
    this.adapter = createEditorAdapter(this.type, this.$refs.editorContainer, {
      initialContent: this.value,
      placeholder: this.placeholder,
      editable: this.editable,
      ...this.options,
    });

    // 监听内容变化
    this.adapter.on('change', ({ html, text, json }) => {
      this.internalUpdate = true;
      this.$emit('input', html); // v-model 绑定
      this.$emit('change', { html, text, json });
      this.$nextTick(() => {
        this.internalUpdate = false;
      });
    });

    this.adapter.on('focus', () => this.$emit('focus'));
    this.adapter.on('blur', () => this.$emit('blur'));
  },

  watch: {
    value(newVal) {
      // 避免循环更新
      if (this.internalUpdate) return;
      if (newVal !== this.adapter.getHTML()) {
        this.adapter.setContent(newVal);
      }
    },
    editable(val) {
      this.adapter.setEditable(val);
    },
  },

  methods: {
    // 暴露给父组件的 API
    getHTML() { return this.adapter.getHTML(); },
    getText() { return this.adapter.getText(); },
    getJSON() { return this.adapter.getJSON(); },
    clear() { this.adapter.clear(); },
    focus() { this.adapter.focus(); },
    insertImage(url, alt) { this.adapter.insertImage(url, alt); },
  },

  beforeDestroy() {
    this.adapter?.destroy();
    this.adapter = null;
  },
};
</script>

<style scoped>
.rich-editor-wrapper {
  border: 1px solid #d9d9d9;
  border-radius: 8px;
  overflow: hidden;
}
.editor-container {
  min-height: 300px;
}
</style>

业务组件使用：

<template>
  <div>
    <RichEditor
      v-model="articleContent"
      type="tiptap"
      placeholder="请输入文章内容..."
      :options="editorOptions"
      @change="onContentChange"
      ref="editor"
    />
    <button @click="handleSubmit">发布</button>
  </div>
</template>

<script>
import RichEditor from '@/components/RichEditor.vue';

export default {
  components: { RichEditor },
  data() {
    return {
      articleContent: '',
      editorOptions: {
        // 传给底层适配器的额外配置
      },
    };
  },
  methods: {
    onContentChange({ html, text }) {
      console.log('纯文本长度:', text.length);
    },
    handleSubmit() {
      const html = this.$refs.editor.getHTML();
      const text = this.$refs.editor.getText();
      // 提交到后端...
    },
  },
};
</script>

六、图片上传完整方案

6.1 上传服务封装

// services/upload.js

/**
 * 通用图片上传服务
 * 支持：直传OSS、服务端中转、Base64
 */
class UploadService {
  constructor(options = {}) {
    this.options = {
      action: '/api/upload',         // 上传接口
      maxSize: 10 * 1024 * 1024,     // 10MB
      accept: ['image/jpeg', 'image/png', 'image/gif', 'image/webp'],
      enableCompress: true,          // 是否压缩
      compressQuality: 0.8,          // 压缩质量
      compressMaxWidth: 1920,        // 压缩最大宽度
      withCredentials: true,
      headers: {},
      ...options,
    };
  }

  /**
   * 上传单个文件
   * @param {File} file
   * @param {Function} onProgress - 进度回调 (percent: number)
   * @returns {Promise<{ url: string, width: number, height: number }>}
   */
  async upload(file, onProgress) {
    // 1. 校验
    this.validate(file);

    // 2. 压缩（可选）
    let processedFile = file;
    if (this.options.enableCompress && file.type !== 'image/gif') {
      processedFile = await this.compress(file);
    }

    // 3. 上传
    return this.doUpload(processedFile, onProgress);
  }

  /**
   * 文件校验
   */
  validate(file) {
    if (!this.options.accept.includes(file.type)) {
      throw new Error(
        `不支持的文件类型: ${file.type}，仅支持: ${this.options.accept.join(', ')}`
      );
    }
    if (file.size > this.options.maxSize) {
      const maxMB = (this.options.maxSize / 1024 / 1024).toFixed(1);
      throw new Error(`文件大小超出限制，最大 ${maxMB}MB`);
    }
  }

  /**
   * 图片压缩
   */
  compress(file) {
    return new Promise((resolve, reject) => {
      const img = new Image();
      const canvas = document.createElement('canvas');
      const ctx = canvas.getContext('2d');

      img.onload = () => {
        let { width, height } = img;
        const maxWidth = this.options.compressMaxWidth;

        // 按比例缩放
        if (width > maxWidth) {
          height = Math.round((height * maxWidth) / width);
          width = maxWidth;
        }

        canvas.width = width;
        canvas.height = height;
        ctx.drawImage(img, 0, 0, width, height);

        canvas.toBlob(
          (blob) => {
            if (!blob) {
              resolve(file); // 压缩失败，返回原文件
              return;
            }
            // 如果压缩后更大，返回原文件
            if (blob.size >= file.size) {
              resolve(file);
              return;
            }
            const compressed = new File([blob], file.name, {
              type: file.type,
              lastModified: Date.now(),
            });
            console.log(
              `[Upload] 压缩: ${(file.size / 1024).toFixed(0)}KB → ${(compressed.size / 1024).toFixed(0)}KB`
            );
            resolve(compressed);
          },
          file.type,
          this.options.compressQuality
        );
      };

      img.onerror = () => resolve(file); // 失败不阻塞
      img.src = URL.createObjectURL(file);
    });
  }

  /**
   * 执行上传（XMLHttpRequest，支持进度）
   */
  doUpload(file, onProgress) {
    return new Promise((resolve, reject) => {
      const xhr = new XMLHttpRequest();
      const formData = new FormData();
      formData.append('file', file);
      formData.append('type', 'editor-image');

      // 进度监听
      xhr.upload.addEventListener('progress', (e) => {
        if (e.lengthComputable && onProgress) {
          const percent = Math.round((e.loaded / e.total) * 100);
          onProgress(percent);
        }
      });

      xhr.addEventListener('load', () => {
        if (xhr.status >= 200 && xhr.status < 300) {
          try {
            const res = JSON.parse(xhr.responseText);
            if (res.code === 0 || res.success) {
              resolve({
                url: res.data?.url || res.url,
                width: res.data?.width,
                height: res.data?.height,
              });
            } else {
              reject(new Error(res.message || '上传失败'));
            }
          } catch (e) {
            reject(new Error('响应解析失败'));
          }
        } else {
          reject(new Error(`上传失败: HTTP ${xhr.status}`));
        }
      });

      xhr.addEventListener('error', () => reject(new Error('网络错误')));
      xhr.addEventListener('abort', () => reject(new Error('上传已取消')));
      xhr.addEventListener('timeout', () => reject(new Error('上传超时')));

      xhr.open('POST', this.options.action);
      xhr.withCredentials = this.options.withCredentials;
      xhr.timeout = 30000;

      // 设置请求头
      Object.entries(this.options.headers).forEach(([key, value]) => {
        xhr.setRequestHeader(key, value);
      });

      xhr.send(formData);

      // 返回取消方法
      this._currentXHR = xhr;
    });
  }

  /**
   * 取消当前上传
   */
  abort() {
    this._currentXHR?.abort();
  }

  /**
   * 批量上传
   */
  async uploadBatch(files, onProgress) {
    const results = [];
    for (let i = 0; i < files.length; i++) {
      const result = await this.upload(files[i], (percent) => {
        onProgress?.({
          current: i + 1,
          total: files.length,
          percent,
          overallPercent: Math.round(
            ((i * 100 + percent) / files.length)
          ),
        });
      });
      results.push(result);
    }
    return results;
  }

  /**
   * 将文件转为 Base64（离线场景降级方案）
   */
  static toBase64(file) {
    return new Promise((resolve, reject) => {
      const reader = new FileReader();
      reader.onload = () => resolve(reader.result);
      reader.onerror = reject;
      reader.readAsDataURL(file);
    });
  }
}

// 单例导出
export const uploadService = new UploadService();
export default UploadService;

6.2 粘贴/拖拽上传

// plugins/paste-upload.js

/**
 * 粘贴图片上传插件（通用，可用于任何编辑器）
 */
export function setupPasteUpload(editorElement, { onUpload, onError }) {
  // 粘贴上传
  const pasteHandler = async (event) => {
    const items = event.clipboardData?.items;
    if (!items) return;

    for (const item of items) {
      if (item.type.startsWith('image/')) {
        event.preventDefault();
        const file = item.getAsFile();
        if (!file) continue;

        try {
          const result = await onUpload(file);
          return result; // 返回给编辑器处理
        } catch (err) {
          onError?.(err);
        }
      }
    }
  };

  // 拖拽上传
  const dropHandler = async (event) => {
    const files = event.dataTransfer?.files;
    if (!files?.length) return;

    for (const file of files) {
      if (file.type.startsWith('image/')) {
        event.preventDefault();
        try {
          const result = await onUpload(file);
          return result;
        } catch (err) {
          onError?.(err);
        }
      }
    }
  };

  const dragOverHandler = (event) => {
    event.preventDefault();
    event.dataTransfer.dropEffect = 'copy';
  };

  editorElement.addEventListener('paste', pasteHandler);
  editorElement.addEventListener('drop', dropHandler);
  editorElement.addEventListener('dragover', dragOverHandler);

  // 返回清理函数
  return () => {
    editorElement.removeEventListener('paste', pasteHandler);
    editorElement.removeEventListener('drop', dropHandler);
    editorElement.removeEventListener('dragover', dragOverHandler);
  };
}

七、XSS 安全防护

7.1 输入过滤（前端）

// utils/sanitize.js

import DOMPurify from 'dompurify';

/**
 * HTML 安全过滤配置
 */
const SANITIZE_CONFIG = {
  // 允许的标签
  ALLOWED_TAGS: [
    // 块级
    'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
    'p', 'div', 'blockquote', 'pre', 'code',
    'ul', 'ol', 'li',
    'table', 'thead', 'tbody', 'tr', 'th', 'td',
    'hr', 'br',
    // 行内
    'strong', 'b', 'em', 'i', 'u', 's', 'del',
    'a', 'img', 'span', 'sub', 'sup', 'mark',
  ],

  // 允许的属性
  ALLOWED_ATTR: [
    'href', 'target', 'rel',
    'src', 'alt', 'width', 'height',
    'class', 'id',
    'style',
    'data-type', 'data-mention-id', 'data-mention-label',
    'colspan', 'rowspan',
  ],

  // 允许的 CSS 属性
  ALLOWED_STYLE_PROPERTIES: [
    'color', 'background-color', 'background',
    'font-size', 'font-weight', 'font-style',
    'text-align', 'text-decoration',
    'margin', 'margin-top', 'margin-bottom', 'margin-left', 'margin-right',
    'padding', 'padding-top', 'padding-bottom', 'padding-left', 'padding-right',
    'border', 'border-radius',
    'width', 'max-width', 'height',
    'display', 'list-style-type',
  ],

  // 允许的 URL 协议
  ALLOWED_URI_REGEXP: /^(?:(?:https?|mailto|tel):|[^a-z]|[a-z+.-]+(?:[^a-z+.-:]|$))/i,

  // 不允许的标签直接移除（而不是转义）
  FORBID_TAGS: ['script', 'style', 'iframe', 'object', 'embed', 'form', 'input'],
  FORBID_ATTR: ['onerror', 'onclick', 'onload', 'onmouseover', 'onfocus'],

  // 链接安全
  ADD_ATTR: ['target'],
};

/**
 * 过滤HTML（用于存储前）
 */
export function sanitizeHTML(dirtyHTML) {
  // 配置钩子：给所有 a 标签加上 rel="noopener noreferrer"
  DOMPurify.addHook('afterSanitizeAttributes', (node) => {
    if (node.tagName === 'A') {
      node.setAttribute('target', '_blank');
      node.setAttribute('rel', 'noopener noreferrer nofollow');
    }
    // img 标签限制来源
    if (node.tagName === 'IMG') {
      const src = node.getAttribute('src') || '';
      // 只允许 https 和 已知 CDN 域名
      const allowedDomains = [
        'your-cdn.com',
        'img.your-domain.com',
        'res.cloudinary.com',
      ];
      try {
        const url = new URL(src);
        if (url.protocol !== 'https:' || !allowedDomains.some(d => url.hostname.endsWith(d))) {
          // 不安全的图片替换为占位图
          node.setAttribute('src', '/images/blocked-image.png');
          node.setAttribute('alt', '图片已被安全策略拦截');
        }
      } catch {
        // data:image base64 允许
        if (!src.startsWith('data:image/')) {
          node.remove();
        }
      }
    }
  });

  const clean = DOMPurify.sanitize(dirtyHTML, SANITIZE_CONFIG);

  // 清除钩子（避免影响后续调用）
  DOMPurify.removeHook('afterSanitizeAttributes');

  return clean;
}

/**
 * 过滤HTML（用于展示，更严格）
 */
export function sanitizeForDisplay(html) {
  return DOMPurify.sanitize(html, {
    ...SANITIZE_CONFIG,
    RETURN_DOM: false,
    RETURN_DOM_FRAGMENT: false,
  });
}

/**
 * 纯文本转义（最安全，用于用户名、标题等）
 */
export function escapeHtml(str) {
  const map = {
    '&': '&amp;',
    '<': '&lt;',
    '>': '&gt;',
    '"': '&quot;',
    "'": '&#x27;',
    '/': '&#x2F;',
  };
  return String(str).replace(/[&<>"'/]/g, (char) => map[char]);
}

7.2 后端二次过滤（Node.js）

// server/middleware/sanitize.js

const createDOMPurify = require('dompurify');
const { JSDOM } = require('jsdom');

const window = new JSDOM('').window;
const DOMPurify = createDOMPurify(window);

/**
 * Express 中间件：过滤请求体中的 HTML 字段
 */
function sanitizeMiddleware(fields = ['content', 'body', 'html']) {
  return (req, res, next) => {
    if (req.body && typeof req.body === 'object') {
      fields.forEach((field) => {
        if (typeof req.body[field] === 'string') {
          req.body[field] = DOMPurify.sanitize(req.body[field], {
            ALLOWED_TAGS: [
              'h1','h2','h3','h4','h5','h6',
              'p','div','blockquote','pre','code',
              'ul','ol','li',
              'table','thead','tbody','tr','th','td',
              'hr','br',
              'strong','b','em','i','u','s','del',
              'a','img','span',
            ],
            ALLOWED_ATTR: [
              'href','target','rel',
              'src','alt','width','height',
              'class','style',
              'data-type','data-mention-id',
            ],
            FORBID_TAGS: ['script','style','iframe','object','embed','form'],
            FORBID_ATTR: ['onerror','onclick','onload','onmouseover'],
          });
        }
      });
    }
    next();
  };
}

module.exports = sanitizeMiddleware;

// 使用：
// app.post('/api/article', sanitizeMiddleware(['content']), articleController.create);

八、性能优化

8.1 大文档性能优化

// optimization/virtual-scroll.js

/**
 * 编辑器虚拟滚动（Slate.js 大文档优化思路）
 *
 * 原理：只渲染可视区域内的块级节点
 * Tiptap/ProseMirror 原生支持较好，一般不需要
 * Slate.js 大文档（>500个块）需要考虑
 */
export class VirtualEditorScroll {
  constructor(editor, container, options = {}) {
    this.editor = editor;
    this.container = container;
    this.options = {
      blockHeight: 40,        // 预估块高度
      overscan: 5,            // 额外渲染行数
      ...options,
    };

    this.visibleRange = { start: 0, end: 50 };
    this.observer = null;

    this.init();
  }

  init() {
    // 使用 IntersectionObserver 监测可见性
    this.observer = new IntersectionObserver(
      (entries) => {
        entries.forEach((entry) => {
          const index = parseInt(entry.target.dataset.blockIndex);
          if (entry.isIntersecting) {
            entry.target.classList.remove('virtualized');
          }
        });
      },
      {
        root: this.container,
        rootMargin: '200px 0px', // 提前200px开始渲染
      }
    );
  }

  /**
   * 获取当前应该渲染的块索引范围
   */
  getVisibleRange() {
    const { scrollTop, clientHeight } = this.container;
    const { blockHeight, overscan } = this.options;
    const totalBlocks = this.editor.children.length;

    const start = Math.max(0, Math.floor(scrollTop / blockHeight) - overscan);
    const end = Math.min(
      totalBlocks,
      Math.ceil((scrollTop + clientHeight) / blockHeight) + overscan
    );

    return { start, end };
  }

  destroy() {
    this.observer?.disconnect();
  }
}

/**
 * 防抖的 onChange（避免高频触发导致的性能问题）
 */
export function createDebouncedOnChange(callback, delay = 300) {
  let timer = null;
  let lastEditorState = null;

  return (editorState) => {
    lastEditorState = editorState;

    if (timer) clearTimeout(timer);
    timer = setTimeout(() => {
      callback(lastEditorState);
      timer = null;
    }, delay);
  };
}

/**
 * 懒加载图片（编辑器内的图片使用懒加载）
 */
export function setupLazyImages(container) {
  const observer = new IntersectionObserver(
    (entries) => {
      entries.forEach((entry) => {
        if (entry.isIntersecting) {
          const img = entry.target;
          if (img.dataset.src) {
            img.src = img.dataset.src;
            img.removeAttribute('data-src');
            observer.unobserve(img);
          }
        }
      });
    },
    { rootMargin: '300px' }
  );

  // 监听 DOM 变化，自动处理新插入的图片
  const mutationObserver = new MutationObserver((mutations) => {
    mutations.forEach((mutation) => {
      mutation.addedNodes.forEach((node) => {
        if (node.nodeType === 1) {
          const images = node.tagName === 'IMG'
            ? [node]
            : node.querySelectorAll('img[data-src]');
          images.forEach((img) => observer.observe(img));
        }
      });
    });
  });

  mutationObserver.observe(container, { childList: true, subtree: true });

  return () => {
    observer.disconnect();
    mutationObserver.disconnect();
  };
}

8.2 编辑器懒加载

// 按需加载编辑器（减少首屏体积）

// Vue 异步组件
const RichEditor = () => ({
  component: import(/* webpackChunkName: "rich-editor" */ '@/components/RichEditor.vue'),
  loading: {
    template: `
      <div style="min-height:300px;display:flex;align-items:center;justify-content:center;
                  border:1px dashed #d9d9d9;border-radius:8px;color:#999;">
        <span>编辑器加载中...</span>
      </div>
    `,
  },
  error: {
    template: `
      <div style="min-height:300px;display:flex;align-items:center;justify-content:center;
                  border:1px dashed #ff4d4f;border-radius:8px;color:#ff4d4f;">
        <span>编辑器加载失败，请刷新重试</span>
      </div>
    `,
  },
  delay: 200,
  timeout: 15000,
});

九、编辑器选型对比总结

9.1 综合对比表

┌─────────────┬──────────┬─────────┬─────────┬─────────┬──────────┐
│    维度       │wangEditor│  Tiptap  │ Slate.js │ Lexical │  Quill   │
├─────────────┼──────────┼─────────┼─────────┼─────────┼──────────┤
│ 框架         │ Vue优先   │ 框架无关  │ React    │ React   │ 框架无关  │
│ 上手难度     │ ⭐⭐       │ ⭐⭐⭐     │ ⭐⭐⭐⭐⭐  │ ⭐⭐⭐⭐   │ ⭐⭐       │
│ 可扩展性     │ ⭐⭐⭐     │ ⭐⭐⭐⭐⭐  │ ⭐⭐⭐⭐⭐  │ ⭐⭐⭐⭐⭐ │ ⭐⭐⭐     │
│ 开箱即用     │ ⭐⭐⭐⭐⭐  │ ⭐⭐⭐⭐   │ ⭐⭐       │ ⭐⭐⭐    │ ⭐⭐⭐⭐   │
│ 协同编辑     │ ✗        │ ✓ (Yjs) │ 需自实现  │ 需自实现 │ 需自实现  │
│ 大文档性能   │ 一般      │ 好       │ 好       │ 最好    │ 一般     │
│ Bundle Size  │ ~200KB   │ ~150KB  │ ~100KB   │ ~60KB   │ ~40KB    │
│ TypeScript   │ ✓        │ ✓       │ ✓        │ ✓       │ ✗        │
│ 中文文档     │ ⭐⭐⭐⭐⭐  │ ⭐⭐      │ ⭐⭐       │ ⭐⭐     │ ⭐⭐⭐     │
│ 社区活跃度   │ 中       │ 高       │ 高       │ 高      │ 中(维护少)│
│ 学习价值     │ ⭐⭐      │ ⭐⭐⭐⭐   │ ⭐⭐⭐⭐⭐  │ ⭐⭐⭐⭐  │ ⭐⭐       │
└─────────────┴──────────┴─────────┴─────────┴─────────┴──────────┘

9.2 选型决策树

你的需求是什么？
│
├── 管理后台 / 内部系统 / 快速交付
│   ├── Vue 项目 → wangEditor ✅
│   └── React 项目 → Quill（简单）或 Lexical（完整）
│
├── 内容创作平台（博客、CMS、知识库）
│   ├── 需要协同编辑 → Tiptap + Yjs ✅
│   ├── 不需要协同 → Tiptap 或 Slate.js
│   └── 类 Notion → Slate.js ✅（最灵活的Block模型）
│
├── 评论 / 反馈 / 轻量输入
│   └── Quill ✅（最小体积，功能够用）
│
├── 大型文档系统（万字+、高性能要求）
│   └── Lexical ✅（Meta出品，性能最优）
│
├── 面试 / 学习编辑器原理
│   └── Slate.js ✅（底层暴露最多，理解最深）
│
└── 需要在 Vue2/3 和 React 间迁移
    └── 适配器模式 + Tiptap（Vue/React都支持） ✅

十、面试高频题

题目1：contentEditable 的原理和问题

Q: 为什么不直接用 contentEditable + execCommand？

A: 核心问题：
1. execCommand 已废弃，各浏览器行为不一致
   - Chrome 按回车产生 <div>，Firefox 产生 <br>，Safari 产生 <div>
   - 加粗可能产生 <b> 或 <strong>

2. 不可控的 DOM 变化
   - 浏览器自行决定如何修改 DOM，无法预测结果
   - 粘贴内容会引入大量脏标签
   - 撤销/重做依赖浏览器原生实现，状态难以管理

3. 选区管理困难
   - Selection/Range API 复杂且跨浏览器不一致
   - 中文输入法（IME）的 compositionstart/end 处理

现代编辑器的解法：
- 维护独立的文档模型（Model）
- 自己控制 DOM 渲染（View）
- 拦截所有输入事件，通过模型操作来更新视图
- 这就是 ProseMirror / Slate 的核心理念

题目2：协同编辑的冲突解决


A: 主流方案对比：

1.  OT（Operational Transformation）—— Google Docs 使用

    *   将操作转换为 Operation（如 insert(pos, text), delete(pos, len)）
    *   当两个操作冲突时，通过转换函数调整：

    示例：
    初始文档："abc"
    用户A：insert(1, 'X') → "aXbc"     在位置1插入X
    用户B：delete(2, 1) → "ab"          删除位置2的c

    如果B先到服务端：

    *   B的操作：delete(2,1) → "ab"
    *   A的操作需要转换：insert(1,'X') 不受影响 → "aXb"

    如果A先到服务端：

    *   A的操作：insert(1,'X') → "aXbc"
    *   B的操作需要转换：原本delete(2,1)，但A在前面插了一个字符
        → 变成 delete(3,1) → "aXb"

    最终结果一致："aXb" ✓

    缺点：

    *   需要中心服务器排序
    *   转换函数复杂度随操作类型指数增长
    *   实现正确性极难保证

2.  CRDT（Conflict-free Replicated Data Type）—— Yjs 使用

    *   每个字符有全局唯一ID（clientId + clock）
    *   字符之间通过"左邻居"和"右邻居"关系定位，而非绝对位置
    *   无需中心服务器，天然最终一致

    示例（Yjs的YATA算法）：
    初始文档：\[a(id:A1), b(id:A2), c(id:A3)]

    用户A在a后插入X：

    *   X(id:B1, leftOrigin:A1, rightOrigin:A2)

    用户B删除c：

    *   标记 A3 为 tombstone（墓碑标记，不真正删除）

    合并时：

    *   X 根据 leftOrigin=A1 找到位置 → 插在a后面
    *   A3 被标记删除 → 不显示
    *   结果："aXb" ✓

    优点：

    *   无需中心服务器
    *   支持离线编辑后合并
    *   数学上可证明最终一致性

    缺点：

    *   内存占用较大（tombstone不释放）
    *   需要 GC 策略清理

题目3：编辑器文档模型设计


Q: 如何设计一个编辑器的文档模型？对比各框架的模型差异。

A:

1.  ProseMirror / Tiptap 模型：

    *   基于 Schema 约束的树形结构
    *   强类型：每个节点类型必须在 Schema 中预定义
    *   严格的嵌套规则（如 paragraph 只能在 doc 内，text 只能在 paragraph 内）

    {
    type: 'doc',
    content: \[
    {
    type: 'heading',
    attrs: { level: 2 },
    content: \[
    { type: 'text', text: 'Hello', marks: \[{ type: 'bold' }] }
    ]
    },
    {
    type: 'paragraph',
    content: \[
    { type: 'text', text: 'World' }
    ]
    }
    ]
    }

    特点：不可变（Immutable），每次修改产生新文档

2.  Slate.js 模型：

    *   自由的树形结构，无 Schema 约束
    *   开发者自己定义什么是合法结构

    \[    {    type: 'heading',    level: 2,    children: \[    { text: 'Hello', bold: true }    ]
    },
    {
    type: 'paragraph',
    children: \[
    { text: 'World' }
    ]
    }
    ]

    特点：格式信息直接放在 text 节点上（而非 marks）

3.  Lexical 模型：

    *   基于类继承的节点系统
    *   每个节点是一个 class 实例，有自己的方法

    class HeadingNode extends ElementNode {
    \_\_tag: 'h1' | 'h2' | 'h3';
    createDOM() { return document.createElement(this.\_\_tag); }
    updateDOM(prevNode, dom) { /\* 增量更新 \*/ }
    }

    特点：双缓冲（current tree + pending tree），类似 React Fiber

4.  Quill 模型（Delta）：

    *   扁平的操作序列，非树形结构

    {
    ops: \[
    { insert: 'Hello', attributes: { bold: true } },
    { insert: '\n', attributes: { header: 2 } },
    { insert: 'World\n' }
    ]
    }

    特点：简单直观，但难以表达复杂嵌套

题目4：如何防止XSS攻击


Q: 富文本编辑器如何防XSS？只做前端过滤够不够？

A: 绝对不够。必须前后端双重过滤。

攻击向量：

1.  直接注入：<script>alert(1)</script>
2.  事件属性：<img src="转存失败，建议直接上传图片文件 x" onerror="alert(1)" alt="转存失败，建议直接上传图片文件">
3.  协议注入：<a href="javascript:alert(1)">click</a>
4.  CSS注入：<div style="background:url(javascript:alert(1))">
5.  编码绕过：<img src="转存失败，建议直接上传图片文件 x" onerror="alert(1)" alt="转存失败，建议直接上传图片文件">
6.  SVG注入：<svg onload="alert(1)">
7.  嵌套绕过：\<scr<script>ipt>alert(1)\</scr</script>ipt>

防御策略（纵深防御）：

┌─────────────────────────────────────────────────┐
│ 第1层：编辑器层面                                 │
│ - 工具栏限制可插入的格式                           │
│ - 粘贴时剥离危险标签（clipboard sanitize）         │
│ - 不支持源码模式（或源码模式也过滤）               │
├─────────────────────────────────────────────────┤
│ 第2层：提交前过滤                                 │
│ - DOMPurify 白名单过滤                           │
│ - 只允许安全标签和属性                            │
├─────────────────────────────────────────────────┤
│ 第3层：服务端过滤（最关键）                        │
│ - 永远不信任前端数据                              │
│ - 服务端再次用 DOMPurify / sanitize-html 过滤     │
│ - 入库前过滤，而非读取时过滤                       │
├─────────────────────────────────────────────────┤
│ 第4层：输出层                                     │
│ - CSP 头：Content-Security-Policy                │
│ - 展示页面禁止 inline script                      │
│ - img 限制 src 域名白名单                        │
├─────────────────────────────────────────────────┤
│ 第5层：HTTP安全头                                 │
│ - X-Content-Type-Options: nosniff                │
│ - X-Frame-Options: SAMEORIGIN                    │
│ - Referrer-Policy: strict-origin                 │
└─────────────────────────────────────────────────┘

题目5：编辑器的选区（Selection）和光标管理


Q: 解释编辑器中选区的概念，为什么操作选区这么复杂？

A:

浏览器原生选区 API：

// 获取选区
const selection = window\.getSelection();
const range = selection.getRangeAt(0);

// Range 的四个关键属性
range.startContainer  // 开始节点（DOM节点）
range.startOffset     // 开始偏移
range.endContainer    // 结束节点
range.endOffset       // 结束偏移

// 选区 = 从 (startContainer, startOffset) 到 (endContainer, endOffset)
// 光标 = 选区折叠（start === end）

复杂的原因：

1.  DOM 位置 ≠ 逻辑位置

    <p>Hello <strong>World</strong></p>

    光标在 "World" 的 W 前面，DOM表示可以是：

    *   (strong的firstChild, 0)     → 在 strong 内部开头
    *   (p, 1)                      → 在 p 的第2个子节点前
    *   ("Hello "文本节点, 6)        → 在文本末尾（视觉上一样）

    三种DOM表示，视觉位置完全相同！

2.  中文输入法（IME）问题
    输入 "中国" 的过程：

    *   compositionstart → 开始组合
    *   compositionupdate："zh" → "zhong" → "中"
    *   compositionupdate："中g" → "中gu" → "中国"
    *   compositionend → 确认输入 "中国"

    在composition 期间，编辑器不能干预DOM，否则输入法会崩溃

    React的受控组件模式 + 中文输入 = 灾难
    → Slate.js 为此做了大量兼容处理

3.  跨节点选区
    选中 "llo Wor" 横跨两个DOM节点：

    <p>He[llo <strong>Wor]ld</strong></p>

    Range: startContainer="Hello ", startOffset=2
    endContainer="World", endOffset=3

    编辑器需要将DOM选区 ↔ 文档模型选区双向映射

各框架的解法：

ProseMirror: 用整数位置（pos）表示，整个文档是扁平的位置序列 <doc>  <p>  H  e  l  l  o  </p>  <p>  W  o  r  l  d  </p>  </doc>
0      1    2  3  4  5  6  7      8    9  10 11 12 13 14     15

选区 = {from: 4, to: 11} 表示 "llo\nWor"
简单直观，但嵌套深时计算复杂

Slate: 用 Path + Offset
选区 = {
anchor: { path: \[0, 0], offset: 2 },  // 第1个块的第1个文本，偏移2
focus:  { path: \[1, 0], offset: 3 },   // 第2个块的第1个文本，偏移3
}

Lexical: 用 NodeKey + Offset
选区 = {
anchor: { key: 'node\_3', offset: 2, type: 'text' },
focus:  { key: 'node\_5', offset: 3, type: 'text' },
}

题目6：编辑器的历史记录（撤销/重做）实现


Q: 如何实现编辑器的撤销/重做？

A: 两种主流方案：

方案1：快照栈（Snapshot Stack）—— 简单但内存大
undo栈: \[state1, state2, state3]  ← 当前
redo栈: \[]

撤销：把 state3 移到 redo，恢复 state2
重做：把 state3 从 redo 移回 undo

优化：

*   用 Immutable.js 结构共享，减少内存
*   限制栈大小（如最多100步）
*   合并连续的相同操作（连续打字合并为一步）

方案2：操作栈（Operation Stack）—— 复杂但高效
undo栈: \[op1, op2, op3]

每个 operation 有对应的 inverse operation：

*   insert("a", pos:5) 的逆操作 = delete(pos:5, len:1)
*   setBold(true, range) 的逆操作 = setBold(false, range)

撤销：执行 op3 的逆操作
重做：重新执行 op3

ProseMirror 就是这种方案，通过 Transaction 的 mapping 来实现

合并策略（将连续小操作合并为一步）：

*   连续字符输入 → 合并为一次文本插入
*   超过一定时间间隔（如500ms）→ 断开，作为新的一步
*   不同类型操作 → 断开
*   手动调用 addMark → 断开

代码示例（简化的快照栈）：

class HistoryManager {
constructor(maxStack = 100) {
this.undoStack = \[];
this.redoStack = \[];
this.maxStack = maxStack;
this.lastPushTime = 0;
this.mergeInterval = 500; // 500ms内的操作合并
}

push(state) {
const now = Date.now();

    // 合并策略：短时间内的操作合并
    if (now - this.lastPushTime < this.mergeInterval && this.undoStack.length > 0) {
      this.undoStack[this.undoStack.length - 1] = state;
    } else {
      this.undoStack.push(state);
      if (this.undoStack.length > this.maxStack) {
        this.undoStack.shift(); // 超出限制，丢弃最早的
      }
    }

    // 新操作清空redo栈
    this.redoStack = [];
    this.lastPushTime = now;

}

undo() {
if (this.undoStack.length <= 1) return null; // 保留初始状态
const current = this.undoStack.pop();
this.redoStack.push(current);
return this.undoStack\[this.undoStack.length - 1]; // 返回上一个状态
}

redo() {
if (this.redoStack.length === 0) return null;
const state = this.redoStack.pop();
this.undoStack.push(state);
return state;
}

canUndo() { return this.undoStack.length > 1; }
canRedo() { return this.redoStack.length > 0; }
}

题目7：如何实现 @ 提及功能

// mention-plugin.js（以Tiptap为例）

import { Extension } from '@tiptap/core';
import { Plugin, PluginKey } from 'prosemirror-state';
import { Decoration, DecorationSet } from 'prosemirror-view';
import Suggestion from '@tiptap/suggestion';

/**
 * @ 提及功能实现思路：
 *
 * 1. 检测输入：监听到 @ 字符时激活
 * 2. 搜索过滤：根据 @ 后的文字搜索用户列表
 * 3. 弹出面板：在光标位置显示候选列表
 * 4. 插入节点：选择后插入特殊的 mention 节点
 * 5. 渲染展示：mention 节点渲染为带样式的标签
 */

// Mention Node 定义
const MentionNode = Node.create({
  name: 'mention',
  group: 'inline',
  inline: true,
  selectable: false,
  atom: true, // 原子节点，不可编辑内部

  addAttributes() {
    return {
      id: { default: null },
      label: { default: null },
    };
  },

  parseHTML() {
    return [{ tag: 'span[data-mention]' }];
  },

  renderHTML({ node }) {
    return [
      'span',
      {
        'data-mention': '',
        'data-mention-id': node.attrs.id,
        class: 'mention-tag',
        style: 'color:#1890ff;background:#e6f7ff;padding:0 4px;border-radius:2px;',
      },
      `@${node.attrs.label}`,
    ];
  },

  // Suggestion 配置
  addProseMirrorPlugins() {
    return [
      Suggestion({
        editor: this.editor,
        char: '@', // 触发字符
        // 当输入 @ 后：
        items: async ({ query }) => {
          // query 是 @ 后面输入的文字
          const users = await fetchUsers(query);
          return users.slice(0, 5); // 最多显示5个
        },
        render: () => {
          let component; // 弹出面板组件实例

          return {
            onStart: (props) => {
              // 在光标位置创建弹出面板
              component = createMentionDropdown(props);
            },
            onUpdate: (props) => {
              component.updateProps(props);
            },
            onKeyDown: (props) => {
              // 方向键 / 回车 交给面板处理
              if (props.event.key === 'Escape') {
                component.destroy();
                return true;
              }
              return component.onKeyDown(props);
            },
            onExit: () => {
              component?.destroy();
            },
          };
        },
        command: ({ editor, range, props }) => {
          // 选择用户后，替换 @xxx 为 mention 节点
          editor
            .chain()
            .focus()
            .insertContentAt(range, [
              {
                type: 'mention',
                attrs: { id: props.id, label: props.name },
              },
              { type: 'text', text: ' ' }, // 后面加个空格
            ])
            .run();
        },
      }),
    ];
  },
});

题目8：编辑器性能优化的具体措施

Q: 编辑器在大文档（10000+字，100+图片）场景下如何优化？

A: 分层优化策略：

┌─ 渲染层优化 ─────────────────────────────────┐
│                                               │
│ 1. 虚拟渲染：只渲染可视区域的块               │
│    - Lexical 原生支持                         │
│    - Slate 需要自己实现                       │
│    - Tiptap/PM 的 NodeView 可以做懒渲染      │
│                                               │
│ 2. 图片懒加载：                               │
│    - IntersectionObserver                     │
│    - 缩略图 + 点击加载原图                    │
│    - 渐进式 JPEG                              │
│                                               │
│ 3. 减少重排（Reflow）：                       │
│    - 固定编辑器高度，内部滚动                 │
│    - 避免动态改变工具栏布局                   │
│    - 使用 transform 代替 top/left             │
│                                               │
├─ 模型层优化 ─────────────────────────────────┤
│                                               │
│ 4. 最小化更新：                               │
│    - ProseMirror: Transaction + Mapping       │
│    - Slate: 操作级 normalize                  │
│    - Lexical: 双缓冲 + 增量 reconcile        │
│                                               │
│ 5. 历史记录优化：                             │
│    - 限制 undo 栈大小                         │
│    - 合并连续操作                             │
│    - 超时快照压缩                             │
│                                               │
│ 6. onChange 防抖：                             │
│    - 不要每次按键都序列化整个文档             │
│    - 用 requestIdleCallback 延迟处理          │
│    - 区分"内容变化"和"选区变化"               │
│                                               │
├─ 网络层优化 ─────────────────────────────────┤
│                                               │
│ 7. 图片上传优化：                             │
│    - 前端压缩后再上传                         │
│    - 并发控制（最多3张同时上传）              │
│    - 失败重试 + 断点续传                      │
│                                               │
│ 8. 自动保存优化：                             │
│    - 增量保存（只传diff）                     │
│    - 节流保存（5秒内最多1次）                 │
│    - 用 Web Worker 做序列化                   │
│                                               │
│ 9. 协同编辑优化：                             │
│    - Awareness 消息合并                       │
│    - 离线操作队列                             │
│    - 连接状态回退（WS → SSE → Polling）      │
│                                               │
├─ 加载优化 ───────────────────────────────────┤
│                                               │
│ 10. 代码分割：                                │
│     - 编辑器组件异步加载                      │
│     - 扩展按需注册                            │
│     - 工具栏代码懒加载                        │
│                                               │
│ 11. 初始化优化：                              │
│     - 先显示骨架屏                            │
│     - 编辑器初始化放到 requestIdleCallback    │
│     - 大文档分块加载（先加载前2屏）           │
│                                               │
└───────────────────────────────────────────────┘

// 实际的性能优化代码示例

// 1. onChange 防抖 + 区分变化类型
function createOptimizedOnChange(editor, callback) {
  let timer = null;
  let pendingOps = [];

  return ({ editorState, dirtyElements, dirtyLeaves, prevEditorState, tags }) => {
    // Lexical 的精确判断
    if (dirtyElements.size === 0 && dirtyLeaves.size === 0) {
      return; // 纯选区变化，忽略
    }

    // 收集变化
    pendingOps.push({ dirtyElements, dirtyLeaves, tags });

    // 防抖
    clearTimeout(timer);
    timer = setTimeout(() => {
      callback({
        editorState,
        changes: pendingOps,
        changeCount: pendingOps.length,
      });
      pendingOps = [];
    }, 300);
  };
}

// 2. 用 Web Worker 做序列化（避免阻塞主线程）
// serializer.worker.js
self.onmessage = function (e) {
  const { type, data } = e.data;

  switch (type) {
    case 'toHTML': {
      // 在 Worker 中执行耗时的序列化
      const html = slateNodesToHTML(data.nodes);
      self.postMessage({ type: 'htmlResult', html });
      break;
    }
    case 'toMarkdown': {
      const md = nodesToMarkdown(data.nodes);
      self.postMessage({ type: 'markdownResult', md });
      break;
    }
  }
};

// 主线程
const worker = new Worker('./serializer.worker.js');

function serializeAsync(nodes) {
  return new Promise((resolve) => {
    worker.onmessage = (e) => {
      if (e.data.type === 'htmlResult') {
        resolve(e.data.html);
      }
    };
    worker.postMessage({ type: 'toHTML', data: { nodes } });
  });
}

// 3. 图片上传并发控制
class UploadQueue {
  constructor(maxConcurrency = 3) {
    this.max = maxConcurrency;
    this.running = 0;
    this.queue = [];
  }

  add(task) {
    return new Promise((resolve, reject) => {
      this.queue.push({ task, resolve, reject });
      this.run();
    });
  }

  async run() {
    while (this.running < this.max && this.queue.length > 0) {
      const { task, resolve, reject } = this.queue.shift();
      this.running++;
      try {
        const result = await task();
        resolve(result);
      } catch (err) {
        reject(err);
      } finally {
        this.running--;
        this.run();
      }
    }
  }
}

// 使用
const uploadQueue = new UploadQueue(3);

async function handleMultipleImages(files) {
  const tasks = Array.from(files).map((file) => () => uploadService.upload(file));
  const results = await Promise.all(tasks.map((t) => uploadQueue.add(t)));
  return results; // [{ url, width, height }, ...]
}

题目9：编辑器测试策略

Q: 富文本编辑器如何做自动化测试？

A:

┌─ 单元测试 ────────────────────────────────────┐
│                                                │
│ 测试文档模型的操作（不涉及DOM）：               │
│ - 插入文本后文档结构是否正确                    │
│ - toggleBold 后 marks 是否正确                  │
│ - 列表缩进后嵌套层级是否正确                    │
│ - 序列化/反序列化是否可逆                       │
│                                                │
│ 工具：Jest / Vitest                             │
│                                                │
│ // 示例（Slate.js）                             │
│ test('toggleBold adds bold mark', () => {       │
│   const editor = createEditor();                │
│   editor.children = [                           │
│     { type:'paragraph',                         │
│       children: [{ text: 'Hello' }] }           │
│   ];                                            │
│   Transforms.select(editor, {                   │
│     anchor: { path:[0,0], offset:0 },           │
│     focus: { path:[0,0], offset:5 },            │
│   });                                           │
│   toggleMark(editor, 'bold');                   │
│   expect(editor.children[0].children[0].bold)   │
│     .toBe(true);                                │
│ });                                             │
│                                                │
├─ 集成测试 ────────────────────────────────────┤
│                                                │
│ 测试编辑器在真实DOM中的行为：                   │
│ - 工具栏按钮点击后编辑器内容变化               │
│ - 快捷键是否生效                               │
│ - 粘贴HTML后内容是否正确                       │
│                                                │
│ 工具：Cypress / Playwright                      │
│                                                │
│ // Cypress 示例                                 │
│ it('bold shortcut works', () => {               │
│   cy.get('.editor').type('Hello');               │
│   cy.get('.editor').type('{selectall}');         │
│   cy.get('.editor').type('{ctrl+b}');            │
│   cy.get('.editor strong')                      │
│     .should('contain', 'Hello');                │
│ });                                             │
│                                                │
├─ E2E 测试 ───────────────────────────────────┤
│                                                │
│ 测试完整用户流程：                              │
│ - 创建文章 → 编辑 → 保存 → 重新打开查看        │
│ - 多人协同编辑 → 内容最终一致                   │
│ - 图片上传 → 保存 → 展示页查看                  │
│                                                │
│ 工具：Playwright（推荐，支持多浏览器）          │
│                                                │
├─ 视觉回归测试 ────────────────────────────────┤
│                                                │
│ 编辑器渲染样式是否正确：                        │
│ - 截图对比                                     │
│ - 不同浏览器渲染一致性                          │
│                                                │
│ 工具：Percy / Chromatic / reg-cli               │
│                                                │
└────────────────────────────────────────────────┘

A2UI：让 AI Agent "说出"用户界面的开放协议

掘金前端

作者王小酱

2026年3月17日 18:48

引言：Agent 时代的 UI 困境

想象这样一个场景——你对一个 AI 助手说："帮我订一张明天晚上 7 点的两人桌。" 如果 Agent 只能回复文本，接下来将是一连串低效的对话："请问哪一天？""什么时间？""几位？"……一个本可以用一个表单瞬间解决的事情，变成了五六个回合的文字乒乓球。

更好的方式显然是：Agent 直接生成一个表单界面，带有日期选择器、时间选择器、人数输入框和确认按钮。用户在 UI 上操作，一次提交，搞定。

但这件"显然更好"的事情，在技术上却极其棘手。Agent 可能运行在远程服务器上，甚至跨越组织的信任边界。它不能直接操控你的 UI，只能发送消息。传统的方案——在 iframe 中嵌入 Agent 返回的 HTML/JavaScript——不仅笨重、风格割裂，还引入了严重的安全隐患。

Google 发起的开源项目 A2UI（Agent-to-User Interface） 就是为了解决这个问题而生的。它定义了一种让 Agent "说 UI" 的通用语言：Agent 发送声明式的 JSON 消息来描述界面的意图，客户端应用用自己原生的组件库来渲染。安全如数据，表达如代码。

一、A2UI 是什么？一句话理解核心理念

A2UI 是一个声明式 UI 协议，而不是一个框架。它的核心思想可以拆成三层：

Agent 生成一段 JSON，描述"我想展示一个标题、一个日期选择器和一个按钮"。这段 JSON 通过任意传输通道（A2A 协议、WebSocket、SSE 等）到达客户端。客户端的 A2UI 渲染器读取 JSON，将抽象的组件描述映射为自己代码库中的原生组件——可以是 Flutter Widget、Angular Component、Lit Web Component 或 React 组件。

这意味着同一份 A2UI JSON 可以在 Web、移动端和桌面端被不同的渲染器渲染为风格统一、性能原生的界面，同时 Agent 完全无法执行任何代码——它只能从客户端预先批准的"组件目录"中选取组件来组合界面。

二、为什么需要 A2UI？三大设计支柱

安全优先。 A2UI 是一种声明式数据格式，不是可执行代码。Agent 不能注入 JavaScript，不能操纵 DOM——它只能请求渲染客户端目录中已经存在的、预先审核过的组件（如 Card、Button、TextField）。安全性由客户端完全掌控。

LLM 友好且支持增量更新。 UI 被表示为一个扁平的组件列表，组件之间通过 ID 引用来建立父子关系，而不是深层嵌套的 JSON 树。这种"邻接表"模型让 LLM 可以逐步生成组件、流式发送，客户端可以渐进式渲染——用户看到界面逐步构建，而不是盯着转圈等待。当需要更新时，只需发送带有已有 ID 的新定义即可，无需重新生成整个 UI。

框架无关且可移植。 Agent 发送的是对组件树和数据模型的抽象描述。渲染的责任完全在客户端。同一份 JSON 可以被 Lit 渲染为 Web Component，被 Flutter 渲染为原生移动控件，被 Angular 渲染为 Angular 组件，甚至未来被 SwiftUI 或 Jetpack Compose 渲染为 iOS 和 Android 原生视图。

三、核心概念详解

3.1 Surface（画布）

Surface 是 A2UI 中承载组件的容器，可以理解为一个完整的 UI 单元——一个对话框、一个侧边栏或一个主视图。每个 Surface 有唯一的 surfaceId，拥有自己的组件树和数据模型。Agent 通过创建、更新和删除 Surface 来管理界面的生命周期。

3.2 组件与邻接表模型

这是 A2UI 最独特的设计决策。传统的 UI 描述通常使用嵌套树结构，但 LLM 生成深层嵌套 JSON 时很容易出错，且难以流式传输和增量更新。A2UI 采用了扁平的邻接表模型：所有组件排成一个列表，每个组件有唯一 ID，通过 ID 引用子组件。

举个例子，一个包含标题和两个按钮的简单界面，在 v0.9 中是这样描述的：根组件 Column 声明子组件列表为 ["greeting", "buttons"]，greeting 是一个 Text 组件，buttons 是一个 Row 组件再引用两个 Button。所有组件平级排列，通过 ID 建立层次关系。

A2UI 提供了一套标准组件目录，按用途分为布局类（Row、Column、List）、展示类（Text、Image、Icon、Divider）、交互类（Button、TextField、CheckBox、DateTimeInput、Slider、ChoicePicker）和容器类（Card、Tabs、Modal）。

3.3 数据绑定

A2UI 将 UI 结构与应用状态分离。每个 Surface 拥有一个 JSON 数据模型，组件通过 JSON Pointer 路径（如 /user/name、/cart/items/0/price）绑定到数据模型中的值。

这种分离带来了强大的响应式更新能力：当 Agent 更新数据模型中的某个路径时，绑定到该路径的所有组件自动更新显示内容，无需重新发送组件定义。同时，交互组件（如 TextField）支持双向绑定——用户输入立即写入本地数据模型，当用户点击提交按钮时，按钮的 Action 从数据模型中解析出最新值发送给 Agent。

动态列表是数据绑定的一个精彩应用：一个模板组件绑定到数据模型中的数组路径，数组中每增加一个元素就自动渲染一个新实例，且模板内的路径自动限定到当前数组元素的作用域。

3.4 消息类型与生命周期

以 v0.9 为例，Agent 与客户端之间通过四种核心消息通信。createSurface 创建画布并指定使用的组件目录。updateComponents 定义或更新 UI 组件。updateDataModel 更新应用状态。deleteSurface 移除一个界面。

一个典型的餐厅预订流程是这样的：Agent 先发送 createSurface 创建画布，然后通过 updateComponents 定义表单结构（标题、人数输入框、提交按钮），再通过 updateDataModel 填充初始数据（日期、人数）。用户修改人数，客户端自动更新本地数据模型。用户点击确认，客户端将按钮 Action 中引用的数据路径解析为当前值，封装为 action 消息发送给 Agent。Agent 处理后可以更新界面或删除 Surface。

3.5 Catalog（组件目录）

Catalog 是 A2UI 安全模型的关键枢纽。它是一个 JSON Schema 文件，定义了 Agent 可以使用的所有组件、函数和主题。客户端告诉 Agent 自己支持哪些 Catalog，Agent 在创建 Surface 时选择一个 Catalog 并锁定。之后 Agent 生成的所有 JSON 都会在双端被验证——Agent 端在发送前验证，客户端在接收后再验证。如果验证失败，客户端会发送 VALIDATION_FAILED 错误，Agent 可以据此自我纠正。

A2UI 团队维护了一个"Basic Catalog"作为起步用的通用组件集，但大多数生产应用会定义自己的 Catalog 来反映自己的设计系统。你可以从零开始定义，也可以导入 Basic Catalog 中的部分组件再扩展自定义组件（如图表、地图、股票行情组件）。Catalog 之间通过 URI 作为唯一标识符进行协商和版本管理。

3.6 传输层

A2UI 是传输无关的——任何能传递 JSON 的机制都可以工作。目前与 A2A 协议和 AG UI 有成熟的集成，REST、WebSocket 和 SSE 在路线图中。消息通常以 JSON Lines（JSONL）格式流式传输，每行一个完整的 JSON 对象。在 A2A 绑定中，A2UI 消息被编码为 DataPart，MIME 类型为 application/json+a2ui。

四、v0.8 → v0.9：从"结构化输出优先"到"提示词优先"

A2UI 的版本演进体现了对 LLM 生成能力更深层的理解。v0.8 被设计为通过 LLM 的"结构化输出"模式生成，依赖深层嵌套和特定的包装结构。v0.9 则做了一次哲学性的转变——为"嵌入系统提示词"而优化。

最直观的变化是组件格式从嵌套键变成了扁平判别器。v0.8 写作 "component": { "Text": { "text": { "literalString": "Hello" } } }，v0.9 则简化为 "component": "Text", "text": "Hello"。数据模型更新从键值对数组变成了标准 JSON 对象。子组件列表从 {"explicitList": [...]} 变成了简单的数组。这些改动大幅减少了 token 消耗，也更符合 LLM 天然擅长生成的 JSON 模式。

v0.9 还引入了几个重要的新能力：createSurface 消息要求指定 catalogId，使目录协商变得显式；新增了 sendDataModel 标志，允许客户端在每条消息的元数据中自动附带完整数据模型，实现"无状态 Agent"模式；引入了 formatString 函数支持字符串插值；以及结构化的 VALIDATION_FAILED 错误反馈机制，让 LLM 可以在"生成-验证-纠正"循环中自我改进。

五、双向交互：Action 与数据同步

A2UI 不只是单向的 UI 推送，它支持完整的双向通信。交互组件（如 Button）可以定义 Action，分为两种：Server Event 发送到 Agent 处理（如提交表单），Local Function Call 在客户端本地执行（如打开 URL、格式化字符串、输入验证）。

Action 中的 context 是一个精心设计的机制——它允许按钮在触发时从数据模型中"摘取"特定路径的当前值，封装成一个简洁的上下文对象发送给 Agent，避免 Agent 需要解析整个数据模型。

v0.9 的 Data Model Sync 更是支持了一种优雅的"口头提交"模式：当 sendDataModel 启用时，用户甚至不需要点击按钮——只要说"好的，提交吧"，客户端会将当前完整数据模型附在消息元数据中，Agent 从元数据中读取所有表单值即可完成处理。

在多 Agent 架构中，协调器（Orchestrator）需要维护 Surface 到子 Agent 的所有权映射，确保用户的 Action 被路由回正确的子 Agent，并且在转发消息时剥离其他 Agent 的数据模型，防止跨 Agent 的数据泄露。

六、生态系统与真实应用

A2UI 不是一个纸上协议——它已经在多个 Google 产品和合作伙伴项目中投入使用。

Google Opal 使用 A2UI 驱动 AI 小应用的动态生成式 UI 系统，让数十万用户可以用自然语言创建、编辑和分享 AI 应用。Flutter GenUI SDK 在底层使用 A2UI 作为服务端 Agent 与 Flutter 应用之间的通信协议，实现跨 iOS、Android、Web、桌面的原生渲染。Google ADK（Agent Development Kit）内置了 A2UI v0.8 标准目录的原生渲染支持。CopilotKit / AG UI 提供了 A2UI 的 Day-zero 兼容，AG UI 作为传输层，A2UI 作为 UI 内容格式，形成互补。

A2UI 与同类方案的定位也值得理解：MCP Apps 让远程服务器通过 iframe 提供完整的 UI 体验，适合服务器完全掌控 UI 的场景；AG UI 是一个前后端连接的传输协议；A2UI 则是 UI 负载本身的格式标准。三者可以组合使用——A2UI + AG UI 用 AG UI 做管道、A2UI 做内容，A2UI + A2A 用 A2A 协议在多 Agent 系统中传递 A2UI 消息。

七、动手试一试

体验 A2UI 最快的方式是运行仓库自带的餐厅查找器 Demo。克隆仓库、设置 Gemini API Key、进入 samples/client/lit 目录运行 npm run demo:all，就能在浏览器中看到一个由 Gemini 驱动的 Agent 实时生成交互式 UI 的完整流程。

如果你想更深入地开发，有三条路径可选：前端开发者可以将 A2UI 渲染器集成到自己的应用中（目前支持 Lit、Angular，React 在路线图中）；后端开发者可以使用 Google ADK 构建生成 A2UI 响应的 Agent；或者直接使用 AG UI/CopilotKit 或 Flutter GenUI SDK 等已内置 A2UI 支持的框架。

结语

A2UI 的出现代表了 Agent 交互范式的一次重要进化——从"Agent 只能说文字"到"Agent 可以说 UI"。它用声明式数据格式解决了安全问题，用邻接表模型解决了 LLM 生成和流式渲染的问题，用框架无关的抽象解决了跨平台问题，用 Catalog 协商机制解决了可扩展性问题。

作为 Google 发起、Apache 2.0 许可的开源项目，A2UI 目前处于 v0.8（稳定）和 v0.9（草案）阶段，正在积极向 v1.0 迈进。如果你正在构建 AI Agent 驱动的应用，无论是对话式界面、企业工作流还是多 Agent 系统，A2UI 都值得关注和尝试。

console.log 骗了我一整个通宵：原来它才是时间旅行者

掘金前端

作者 kyriewen

2026年3月17日 18:30

引言

“这个 bug 我明明修好了，为什么控制台还在报错？”

凌晨三点，我盯着屏幕上的代码，眼袋比眼睛还大。明明我已经在 15 行打印了 user.name，显示的是 '张三'；到 30 行修改了 user.name = '李四'，然后又在 45 行打印了一次，结果控制台第一次打印的地方展开一看，居然也变成了 '李四'！

那一刻我差点把电脑吃了——难道代码在时间旅行？还是说 JavaScript 引擎有自己的想法？

直到隔壁工位的老王路过，瞄了一眼我的屏幕，幽幽地说：“小伙子，你也被 console.log 骗了吧？”

一、案发现场：被篡改的历史记录

先来看一段“案发代码”：

const user = { name: '张三', age: 18 };
console.log(user); // 打印 user
user.name = '李四';
console.log(user); // 打印修改后的 user

你觉得控制台会输出什么？按照常理，应该是两次不同的对象：第一次 {name: '张三', age: 18}，第二次 {name: '李四', age: 18}。

但如果你在 Chrome 控制台里运行，展开第一次打印的那个对象，你会发现——它也是 {name: '李四', age: 18}！仿佛历史被篡改了一样。

二、为什么 console.log 会说谎？

2.1 凶手是谁？

答案是：引用类型 + 控制台的“惰性”展示。

当你执行 console.log(user) 时，浏览器并没有立刻把 user 对象的快照保存下来，而是保存了对象的引用。在控制台的界面上，对象是可展开的，当你点击展开图标时，控制台才会去读取当前内存中该对象的属性值。

也就是说，console.log 打印的是一个“活的”对象——它像一台摄像机，记录的不是当时的照片，而是一个实时直播的摄像头。等你点开看的时候，看到的是直播画面，而非当时的回放。

2.2 基本类型为什么没问题？

let name = '张三';
console.log(name); // '张三'
name = '李四';
console.log(name); // '李四'

这里打印的都是基本类型，不会出现篡改历史的问题，因为基本类型是直接存储值，没有引用关系。控制台直接显示当时的字符串值。

2.3 浏览器们的小心思

Chrome/Edge：上面描述的行为最常见。你第一次打印的对象，展开后可能会显示最新的值。
Firefox：早期版本也有类似问题，但现在似乎在打印时会对对象进行“快照”？具体版本有差异。
Safari：表现也不同，有时会保留快照。

所以跨浏览器调试时更要小心——你以为 Safari 没毛病，结果 Chrome 给你来个篡改。

三、真实案例：因为一个 console.log 通宵加班

我曾经维护过一个老项目，有一个函数负责更新用户信息，其中有一段：

function updateUser(user) {
  console.log('更新前：', user); // 调试用
  user.name = '新名字';
  console.log('更新后：', user); // 调试用
  saveToServer(user);
}

当时我发现控制台里两个 log 展开后 name 都是 '新名字'，于是以为 saveToServer 之前 user 已经被改过了，所以怀疑其他代码也修改了 user 引用。我在整个项目里搜索，一无所获。

后来我用 JSON.stringify 打印：

console.log('更新前：', JSON.stringify(user));

终于看到真实的“当时的值”是旧名字。原来 user 对象根本没有被外部修改，是 console.log 骗了我！

四、如何让 console.log 说真话？

4.1 快照大法：深拷贝

在打印前把对象深拷贝一份：

console.log('user 当时的值：', JSON.parse(JSON.stringify(user)));

注意：这种方法无法处理循环引用、函数、undefined、Symbol 等，但对于普通对象足够了。

4.2 展开运算符？小心！

console.log({ ...user });

这样会创建一个新的对象，但它的属性值如果是引用类型，仍然是指向原对象的引用。比如 user.friends 是一个数组，展开后 friends 还是原来的数组，之后修改 user.friends.push('王五')，你打印的那个副本里的 friends 也会变。所以只适用于一层浅拷贝。

4.3 用 console.table 打印表格

对于数组或对象，console.table 会生成一个表格，它会取打印时刻的值，但同样可能受引用影响？实际上 console.table 也是读取当前属性值，所以如果之后修改了原始对象，表格里的数据不会自动更新（因为已经渲染成静态表格了）。这一点比展开对象要可靠。

4.4 使用断点 debugger

最好的办法：直接打断点，在 Sources 面板里查看作用域中的变量值，那是真正的“当时的值”。

debugger; // 代码执行到这里会暂停，你可以慢慢看变量

4.5 自定义一个 safeLog

function safeLog(...args) {
  args.forEach(arg => {
    if (typeof arg === 'object' && arg !== null) {
      console.log(JSON.parse(JSON.stringify(arg)));
    } else {
      console.log(arg);
    }
  });
}

五、其他类似的“时间旅行”陷阱

5.1 数组的 console.log

同样的问题，数组也是对象。

const arr = [1, 2, 3];
console.log(arr); // 展开后可能变成 [1,2,3,4]
arr.push(4);

5.2 异步中的闭包

for (var i = 0; i < 3; i++) {
  setTimeout(() => {
    console.log(i); // 全是 3
  }, 100);
}

这不是 console 的问题，而是闭包捕获了同一个变量。但也是常见的“以为当时的值是 0,1,2”的坑。

5.3 事件监听中的“旧”数据

let count = 0;
button.addEventListener('click', () => {
  console.log(count); // 每次点击打印最新的 count，而不是绑定时的值
});

这也不是 console 的问题，但同样是“值”与“引用”的区别。

六、总结：别太相信 console.log，它只是个演员

console.log 是我们调试的利器，但它也有自己的脾气。理解它的行为，才能避免在 bug 排查时被误导。

记住：打印对象时，控制台保留的是引用，展开时看到的是当前值。
对策：深拷贝、console.table、断点，或者打印基本类型。
心态：遇到奇怪现象，先怀疑工具，再怀疑代码。

最后，分享一个老程序员的玩笑：“当你把 console.log 删干净之后，bug 就消失了。”——有时候，真的是 console.log 在搞鬼。

每日一问：你在调试时还遇到过哪些让人抓狂的“假象”？是 console.log 的延时？还是 sourcemap 错位？欢迎在评论区吐槽，让我们一起长点记性！

（本文虚构故事如有雷同，纯属你也经历过）

在浏览器控制台调试的 6 个秘密技巧

掘金前端

作者冴羽

2026年3月17日 18:19

有一些神奇的快捷键只在浏览器 DevTools 控制台中工作，但它们绝对是调试时的秘密武器。

技巧 1：$0：最后选中的元素

单击“元素”选项卡中的任意元素，然后切换到控制台：

$0; // 查看元素
$0.style.backgroundColor = "red"; // 修改样式
$0.classList.add("highlight"); // 添加类名

更棒的是：$1、$2、$3、$4 会引用最后选中的 5 个元素。非常适合快速比较或操作多个元素。

技巧 2：$$：更优的选择器

忘掉 document.querySelectorAll() 吧，以后使用 $$：

// 旧方式
Array.from(document.querySelectorAll(".product-card")).forEach((card) => console.log(card.textContent));

// 新方式
$$(".product-card").forEach((card) => console.log(card.textContent));

$$() 返回一个真正的数组（而非 NodeList），因此你可以立即使用数组方法。无需再用 Array.from() 包装一层。

技巧 3：$：快速 querySelector

$("#header"); // 等同于 document.querySelector('#header')
$(".btn-primary"); // 等同于 document.querySelector('.btn-primary')

注意： 这仅在 jQuery 未加载时有效。

如果加载了 jQuery，$ 就是 jQuery。

技巧 4：$_：最后一个结果

2 + 2; // 4

$_ * 10; // 40

$_ 存储控制台中最后一个表达式的计算结果。这对于无需重新输入即可链式执行操作非常有用。

技巧 5：copy()：即时剪贴板

const data = { users: [...], products: [...] };
copy(data);

无需再右键单击并选择“复制对象”，也无需尝试将文本字符串化并选中。只需copy(anything)点击一下，它就复制到剪贴板了。

技巧 6：getEventListeners() 事件检查器

getEventListeners($0);

这对于调试事件处理器问题或查找未移除的监听器导致的内存泄漏非常有用。

最后

正确的调试技巧可以为你节省数小时的试错时间。

但比这些快捷键更有价值的，是一种「工具思维」的习惯。

当你不再把 DevTools 看作一个静态的调试面板，而是一个可以对话、可以编程、可以无限扩展的工作台时，你的调试方式就会发生质变。

每一次敲击 $0 或 copy()，本质上都是在训练一种能力：用最小的摩擦，把想法变成验证。

真正的效率不在于记住多少快捷键，而在于你是否愿意停下来，花十分钟学习一个能每天为你节省一分钟的工具。

这种「时间复利」的思维方式，才是优秀开发者与普通开发者的分水岭。掌握这些工具，让自己成为那个在控制台里游刃有余、从容应对复杂问题的人。

我是冴羽，10 年笔耕不辍，专注前端领域，更新了 10+ 系列、300+ 篇原创技术文章，翻译过 Svelte、Solid.js、TypeScript 文档，著有小册《Next.js 开发指南》、《Svelte 开发指南》、《Astro 实战指南》。

欢迎围观我的“网页版朋友圈”，关注我的公众号：冴羽（或搜索 yayujs），每天分享前端知识、AI 干货。

掘金前端
同题画图大考，AiPy 章鱼适配性拉满，OpenClaw 龙虾全程 “哑火”Ekehlaft
2026年3月17日 17:51

同题画图大考，AiPy 章鱼适配性拉满，OpenClaw 龙虾全程 “哑火”

掘金前端

作者 Ekehlaft

2026年3月17日 17:51

作为一名长期关注AI生产力的创作者，我决定用一个硬核测试来验证各大模型的真实能力：让AI控制Windows画图软件，画一辆汽车

这不是简单的文本生成测试，而是一场对AI系统操控能力的全面检验。

一、测试背景：为什么选择"画图"这个场景？

很多人觉得大模型只能聊聊天、写写文案，其实不然。随着AI原生应用的兴起，大模型正逐渐从"对话工具"向"操作系统助手"转变。

本次测试的核心目的，就是验证不同大模型控制鼠标自动操作电脑的能力：

各大模型到底能不能找到Windows电脑上的画图软件？
能不能操作鼠标在正确的位置开始作画？
画出来的图形到底准确不准确？

为保证公平，所有测试都在同一台Windows 11电脑上完成，使用统一的AiPY Pro 0.14.1作为控制平台，提示词固定为："打开Windows画图软件，控制鼠标画一个汽车"。

二、章鱼开画：一气呵成

当任务交给AiPy时，过程非常顺畅：

指令理解阶段：准确拆解任务为"启动画图软件→最大化窗口→选择铅笔工具→绘制汽车各部分→保存文件"5个步骤
代码生成阶段：生成的PyAutoGUI代码逻辑清晰，坐标计算准确，考虑了窗口定位、等待时间等细节
执行阶段：鼠标移动流畅，绘制顺序合理
完成效果：汽车比例协调，线条流畅，细节完整，最终自动保存为PNG文件到指定目录

整个过程完全不需要人工干预，从启动软件到保存结束，Gemini 3.1 Pro在AiPy章鱼平台上耗时100秒，顺利完成了画图任务。虽然完成质量算不上顶级，但它确实做到了。

三、龙虾登场：全程哑火

在章鱼顺利完成测试后，我换成OpenClaw，使用完全相同的Gemini 3.1 Pro模型，输入同样的提示词，再来一次。

结果出人意料：

耗时20秒，一笔未画，全程哑火。

从启动到结束，全程20秒，模型响应了，但是什么都没干

四、为什么差距这么大？

同样的模型，同样的任务，为什么章鱼能行，龙虾不行？从我这次测试的结果来看，差距主要体现在三个方面：

1. 适配性差距

AiPy Pro作为一款专注于系统控制的AI软件，对各大模型生成的代码格式、坐标计算、执行逻辑都做了深度适配优化。大模型输出的PyAutoGUI代码，能被准确解析并转化为实际的鼠标键盘操作。

而OpenClaw在这方面显然存在适配缺陷。同样的代码，在AiPy平台能跑，在龙虾平台就是执行不了。

2. 场景理解差距

AiPy的设计定位非常清晰：让大模型拥有"动手能力"，成为真正能够操作电脑的生产力工具。从做PPT到分析股票再到爬虫，所有功能都围绕"解决实际问题"展开。

OpenClaw给人的感觉，更偏向于框架层面的搭建，对于具体使用场景的打磨还不够深入。当遇到画图这种需要精确坐标和流畅执行的任务，短板立刻显现。

3. 用户体验差距

在AiPy平台上，整个执行过程清晰可见，代码运行、鼠标移动都能实时反馈，就算出错也能快速定位问题。

而在OpenClaw这次测试中，程序说"执行完成"，但屏幕上什么都没发生，用户连问题出在哪都不知道。这种体验对于想要用AI干活的用户来说，几乎是不可接受的。

在这场画图大考中，AiPy章鱼用实际行动证明了：好的AI工具，就是要让大模型能干活、会干活，干好活。适配性不是小事，是决定AI工具生死存亡的大事。

未来，越来越多的任务会交给AI去执行——自动整理Excel、批量处理文件、操作专业软件……只有那些真正做好适配的框架，才能在AI生产力的浪潮中站稳脚跟。

别再手动调 Prompt 了！这款开源神器让 AI 输出质量提升 300%，支持 Claude、GPT、Gemini，还免费开源！

掘金前端

作者前端Hardy

2026年3月17日 17:44

你是不是也这样？

写 10 版提示词，AI 还是答非所问
想让小模型做角色扮演，结果它“人格分裂”
提取知识图谱，输出格式天天变
本地部署 Ollama，但 Web 工具连不上……

而今天，我要介绍的这个 GitHub 23k Star 的开源神器，能一键优化你的提示词，让 GPT-4、Claude、Gemini 甚至 7B 小模型都稳定输出高质量结果。

更惊人的是——
纯前端，数据不上传
支持 Chrome 插件，边写边优化
内置文生图（T2I）和图生图（I2I）
可私有化部署，还能接入 Claude Desktop
完全免费 + 开源 + 中文友好

它就是 —— Prompt Optimizer（提示词优化器）。

一、为什么你需要一个“提示词优化器”？

大模型很强大，但提示词的质量决定输出上限。
普通用户写：“写一首诗” → AI 随便糊弄。
高手写：“以‘春夜细雨’为主题，七言绝句，押平水韵，意象含柳、灯、纸伞，情感含蓄哀而不伤” → 出精品。

但没人天生会写好 Prompt。
而 Prompt Optimizer 能自动帮你把模糊需求转化为精准指令，并支持多轮迭代优化。

它不是“替代你思考”，而是“放大你的意图”。

二、三大核心场景，效果炸裂

场景 1：激发小模型潜力（降本增效）

在成本敏感或隐私要求高的场景（如本地 Ollama），结构化提示词能让 Qwen2.5-7B 稳定扮演“--”，对话一致性提升 300%。

无需微调，仅靠提示词工程，小模型也能“演得像”。

场景 2：保障生产环境稳定性

当你要程序化解析文本（如提取知识图谱），高质量提示词能让 输出格式 100% 符合 JSON Schema，避免后端解析崩溃。

降低对模型智能度的要求，经济的小模型也能扛生产。

场景 3：辅助创意探索

从“写首诗”到“指定意象+情感+格律”，工具帮你把模糊灵感细化为可执行指令，与 AI 共创独一无二的作品。

三、五大隐藏能力，远超想象

能力	说明
双模式优化	同时优化系统提示词（System Prompt）和用户提示词（User Prompt）
多模型集成	支持 OpenAI、Gemini、DeepSeek、智谱、SiliconFlow、Ollama（兼容 OpenAI 接口）
图像生成	内置 T2I（文生图）和 I2I（图生图），支持 Gemini、Seedream
高级测试模式	上下文变量管理、多轮会话测试、Function Calling 调试
纯客户端架构	所有数据直连 AI 服务商，不经过任何中间服务器

甚至支持 MCP 协议，可直接在 Claude Desktop 中调用优化服务！

四、四种使用方式，总有一款适合你

在线体验（最快）

直接访问：prompt.always200.com

无需安装
数据仅存浏览器本地
支持所有核心功能

Chrome 插件（最方便）

安装地址：Chrome 商店
点击图标即可打开优化器
边写提示词边优化

桌面应用（最稳定）

下载地址：GitHub Releases
无跨域限制（可直连本地 Ollama）
自动更新
独立运行，性能更强

Docker 私有化部署（最安全）

docker run -d -p 8081:80 \
  -e VITE_OPENAI_API_KEY=your_key \
  -e ACCESS_PASSWORD=your_password \
  --name prompt-optimizer \
  linshen/prompt-optimizer

支持访问密码保护
国内镜像加速：registry.cn-guangzhou.aliyuncs.com/prompt-optimizer/prompt-optimizer

五、为什么它能火遍全球？

真正解决痛点：不是玩具，而是生产级工具
极致用户体验：Web + 桌面 + 插件 + Docker 全覆盖
开源精神：AGPL-3.0 协议，可商用但需开源衍生作品
社区驱动：23k+ Star，2.8k+ Fork，23 位贡献者

项目文档极其完善：Vercel 部署指南、MCP 使用说明

六、如何开始？30 秒上手

打开 prompt.always200.com
在左侧输入你的原始提示词（如“写一首关于春天的诗”）
点击“优化提示词”
查看优化前后对比，一键复制！

首次使用？点击右上角⚙️配置你的 API 密钥（OpenAI/Gemini/DeepSeek 等）

结语：好工具，值得被更多人看见

在这个 AI 爆发的时代，
不会写 Prompt 的人，正在被会用工具的人甩开。

而 Prompt Optimizer 的出现，
让普通人也能写出接近专家级的提示词。

它不炫技，不炒作，
只是默默帮你——
把“随便问问”，变成“精准得到”。

抓紧转发给你身边有需要的人吧

在线体验：prompt.always200.com
GitHub：github.com/linshenkx/p…

各位互联网搭子，要是这篇文章成功引起了你的注意，别犹豫，关注、点赞、评论、分享走一波，让我们把这份默契延续下去，一起在知识的海洋里乘风破浪！

富文本编辑器知识体系(一)

掘金前端

作者小小小小宇

2026年3月17日 17:41

前端富文本编辑器技术选型完全指南

一、富文本编辑器的三大技术流派

在深入选型之前，先理解富文本编辑器的底层实现原理差异：

┌─────────────────────────────────────────────────────────────────┐
│                    富文本编辑器技术流派                            │
├──────────────────┬──────────────────┬───────────────────────────┤
│   L0: 基于          │  L1: 基于           │  L2: 完全自绘制            │
│   contentEditable   │  contentEditable    │  不依赖浏览器              │
│   + execCommand     │  + 自定义 Model     │  contentEditable          │
├──────────────────┼──────────────────┼───────────────────────────┤
│ 浏览器原生能力       │ 接管数据模型         │ 自己实现光标、选区、       │
│ 简单但不可控        │ 可控性大幅提升       │ 排版、渲染                 │
├──────────────────┼──────────────────┼───────────────────────────┤
│ 代表:             │ 代表:              │ 代表:                      │
│ - UEditor         │ - Slate.js         │ - Google Docs              │
│ - wangEditor(v4) │ - ProseMirror      │ - 腾讯文档                  │
│ - Quill(部分)    │ - Tiptap           │ - Canvas/自定义渲染         │
│                   │ - Draft.js         │                            │
│                   │ - Lexical          │                            │
└──────────────────┴──────────────────┴───────────────────────────┘

二、主流编辑器横向对比

2.1 一览表

维度	wangEditor	Quill	TinyMCE	Slate.js	ProseMirror	Tiptap	Lexical
技术架构	L0→L1	L0/L1混合	L0	L1	L1	L1(基于ProseMirror)	L1
框架依赖	无(v5)	无	无	React	无	Vue/React	React
学习曲线	⭐⭐	⭐⭐⭐	⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐
可扩展性	中	中	中高	极高	极高	高	极高
开箱即用	✅ 极好	✅ 好	✅ 极好	❌ 需大量开发	❌ 需大量开发	✅ 好	⚠️ 一般
协同编辑	❌	❌	付费插件	需自行实现	Yjs集成	Yjs集成	需自行实现
中文支持	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐	⭐⭐⭐	⭐⭐⭐
包体积	~200KB	~40KB	~400KB+	~100KB	~100KB	~150KB	~60KB
维护状态	活跃	较慢	活跃(商业)	活跃	活跃	活跃	活跃(Meta)
适用场景	CMS/后台	轻量评论	企业级CMS	定制编辑器	定制编辑器	中高定制	高性能场景
协议	MIT	BSD	MIT/商业	MIT	MIT	MIT	MIT

2.2 选型决策树

你的需求是什么？
│
├── 快速上线，功能标准，后台管理系统
│   ├── Vue 项目 → wangEditor v5 或 Tiptap
│   ├── React 项目 → Tiptap(@tiptap/react) 或 Lexical
│   └── 不限框架 → TinyMCE（功能最全）或 wangEditor
│
├── 需要高度定制（自定义块、嵌套结构、特殊交互）
│   ├── React 项目 → Slate.js（最灵活）或 Lexical
│   ├── Vue 项目 → Tiptap（基于ProseMirror，生态好）
│   └── 不限框架 → ProseMirror（底层能力最强）
│
├── 需要协同编辑
│   ├── 预算充足 → TinyMCE 商业版
│   └── 开源方案 → Tiptap + Yjs / ProseMirror + Yjs
│
├── 轻量级（评论框、简单富文本）
│   └── Quill 或 wangEditor（配置精简模式）
│
└── 超大文档、极致性能
    └── Lexical（Meta出品，虚拟化渲染）

三、各方案详细代码实战

3.1 wangEditor v5 —— 开箱即用之王

适用场景： 后台管理系统、CMS、博客编辑、中文场景

安装

npm install @wangeditor/editor @wangeditor/editor-for-vue
# Vue3:
# npm install @wangeditor/editor @wangeditor/editor-for-vue@next

Vue 2 完整示例

<template>
  <div class="editor-wrapper">
    <!-- 工具栏 -->
    <Toolbar
      :editor="editor"
      :defaultConfig="toolbarConfig"
      :mode="mode"
      class="toolbar"
    />
    <!-- 编辑区 -->
    <Editor
      :defaultConfig="editorConfig"
      :mode="mode"
      v-model="html"
      class="editor"
      @onCreated="handleCreated"
      @onChange="handleChange"
    />

    <!-- 预览 -->
    <div class="preview">
      <h3>输出 HTML：</h3>
      <div v-html="html" class="preview-content"></div>
    </div>
  </div>
</template>

<script>
import { Editor, Toolbar } from '@wangeditor/editor-for-vue';
import '@wangeditor/editor/dist/css/style.css';

export default {
  name: 'WangEditorDemo',
  components: { Editor, Toolbar },

  data() {
    return {
      editor: null,
      html: '<p>Hello <strong>wangEditor</strong>！</p>',
      mode: 'default', // 或 'simple' 精简模式

      // 工具栏配置
      toolbarConfig: {
        // 排除不需要的功能
        excludeKeys: [
          'fullScreen', // 排除全屏
          'group-video', // 排除视频
        ],
        // 或者用 toolbarKeys 自定义工具栏顺序
        // toolbarKeys: [ 'bold', 'italic', 'underline', '|', ... ]
      },

      // 编辑器配置
      editorConfig: {
        placeholder: '请输入内容...',
        // 所有粘贴配置
        MENU_CONF: {
          // 上传图片配置
          uploadImage: {
            server: '/api/upload/image',
            fieldName: 'file',
            maxFileSize: 5 * 1024 * 1024, // 5MB
            maxNumberOfFiles: 10,
            allowedFileTypes: ['image/*'],
            // 自定义请求头
            headers: {
              Authorization: 'Bearer xxx',
            },
            // 自定义插入图片（服务端返回格式不统一时）
            customInsert(res, insertFn) {
              const { url, alt, href } = res.data;
              insertFn(url, alt, href);
            },
            // 上传进度回调
            onProgress(progress) {
              console.log('上传进度:', progress);
            },
            onSuccess(file, res) {
              console.log('上传成功:', file.name);
            },
            onFailed(file, res) {
              console.error('上传失败:', file.name);
            },
            onError(file, err, res) {
              console.error('上传错误:', err);
            },
          },

          // 上传视频配置
          uploadVideo: {
            server: '/api/upload/video',
            fieldName: 'file',
            maxFileSize: 100 * 1024 * 1024, // 100MB
          },

          // 代码高亮语言配置
          codeSelectLang: {
            codeLangs: [
              { text: 'JavaScript', value: 'javascript' },
              { text: 'TypeScript', value: 'typescript' },
              { text: 'HTML', value: 'html' },
              { text: 'CSS', value: 'css' },
              { text: 'Python', value: 'python' },
              { text: 'Java', value: 'java' },
            ],
          },
        },
      },
    };
  },

  methods: {
    handleCreated(editor) {
      this.editor = Object.seal(editor); // 用 Object.seal 冻结 editor
      console.log('编辑器创建完成', editor);
    },

    handleChange(editor) {
      // 获取纯文本
      const text = editor.getText();
      // 获取 HTML
      const html = editor.getHtml();
      // 获取 JSON（结构化数据）
      const json = editor.children;

      console.log('内容变化:', { textLength: text.length });

      // 你可以在这里做自动保存、字数统计等
      this.$emit('change', { html, text, json });
    },

    // 外部调用：获取内容
    getContent() {
      return {
        html: this.editor.getHtml(),
        text: this.editor.getText(),
        json: this.editor.children,
      };
    },

    // 外部调用：设置内容
    setContent(html) {
      this.editor.setHtml(html);
    },

    // 外部调用：清空内容
    clear() {
      this.editor.clear();
    },

    // 外部调用：禁用/启用编辑
    toggleDisable(disabled) {
      if (disabled) {
        this.editor.disable();
      } else {
        this.editor.enable();
      }
    },
  },

  // 组件销毁时，销毁编辑器
  beforeDestroy() {
    if (this.editor) {
      this.editor.destroy();
    }
  },
};
</script>

<style scoped>
.editor-wrapper {
  border: 1px solid #e8e8e8;
  border-radius: 4px;
  overflow: hidden;
}
.toolbar {
  border-bottom: 1px solid #e8e8e8;
}
.editor {
  height: 400px;
  overflow-y: auto;
}
.preview {
  padding: 16px;
  border-top: 1px dashed #e8e8e8;
  background: #fafafa;
}
.preview-content {
  padding: 12px;
  background: white;
  border: 1px solid #eee;
  border-radius: 4px;
  min-height: 100px;
}
</style>

自定义扩展：@提及功能

// mention-plugin.js
import { Boot } from '@wangeditor/editor';

// 定义 mention 元素节点
const mentionModule = {
  // 注册新元素
  editorPlugin(editor) {
    const { isInline, isVoid } = editor;

    // mention 是行内元素
    editor.isInline = (elem) => {
      if (elem.type === 'mention') return true;
      return isInline(elem);
    };

    // mention 是 void 元素（不可编辑内部）
    editor.isVoid = (elem) => {
      if (elem.type === 'mention') return true;
      return isVoid(elem);
    };

    return editor;
  },

  // 渲染为 HTML
  elemsToHtml: [
    {
      type: 'mention',
      elemToHtml: (elem) => {
        const { value, info } = elem;
        return `<span data-w-e-type="mention" data-w-e-is-void data-w-e-is-inline data-value="${value}" data-info='${JSON.stringify(info)}'>@${info.name}</span>`;
      },
    },
  ],

  // 从 HTML 解析
  parseElemsHtml: [
    {
      selector: 'span[data-w-e-type="mention"]',
      parseElemHtml: (domElem) => {
        const value = domElem.getAttribute('data-value') || '';
        const info = JSON.parse(domElem.getAttribute('data-info') || '{}');
        return { type: 'mention', value, info, children: [{ text: '' }] };
      },
    },
  ],

  // 渲染到编辑器
  renderElems: [
    {
      type: 'mention',
      renderElem: (elem) => {
        const span = document.createElement('span');
        span.style.cssText = 'color: #1890ff; background: #e6f7ff; padding: 0 4px; border-radius: 2px; cursor: pointer;';
        span.textContent = `@${elem.info?.name || ''}`;
        return span;
      },
    },
  ],
};

// 注册模块
Boot.registerModule(mentionModule);

3.2 Tiptap —— 现代化最佳实践

适用场景： 中高度定制需求、Notion-like 编辑器、需要协同编辑

安装

# 核心
npm install @tiptap/vue-2 @tiptap/starter-kit

# 常用扩展
npm install @tiptap/extension-image @tiptap/extension-link \
  @tiptap/extension-placeholder @tiptap/extension-code-block-lowlight \
  @tiptap/extension-color @tiptap/extension-text-style \
  @tiptap/extension-task-list @tiptap/extension-task-item \
  @tiptap/extension-table @tiptap/extension-table-row \
  @tiptap/extension-table-cell @tiptap/extension-table-header \
  @tiptap/extension-character-count

# 代码高亮
npm install lowlight

Vue 2 完整示例

<template>
  <div class="tiptap-editor" :class="{ focused: isFocused }">
    <!-- 工具栏 -->
    <div v-if="editor" class="toolbar">
      <!-- 标题 -->
      <div class="toolbar-group">
        <select
          :value="currentHeading"
          @change="setHeading($event.target.value)"
          class="toolbar-select"
        >
          <option value="paragraph">正文</option>
          <option value="1">标题 1</option>
          <option value="2">标题 2</option>
          <option value="3">标题 3</option>
          <option value="4">标题 4</option>
        </select>
      </div>

      <div class="toolbar-divider"></div>

      <!-- 基础格式 -->
      <div class="toolbar-group">
        <button
          @click="editor.chain().focus().toggleBold().run()"
          :class="{ active: editor.isActive('bold') }"
          title="加粗 (Ctrl+B)"
        >
          <strong>B</strong>
        </button>
        <button
          @click="editor.chain().focus().toggleItalic().run()"
          :class="{ active: editor.isActive('italic') }"
          title="斜体 (Ctrl+I)"
        >
          <em>I</em>
        </button>
        <button
          @click="editor.chain().focus().toggleStrike().run()"
          :class="{ active: editor.isActive('strike') }"
          title="删除线"
        >
          <s>S</s>
        </button>
        <button
          @click="editor.chain().focus().toggleCode().run()"
          :class="{ active: editor.isActive('code') }"
          title="行内代码"
        >
          &lt;/&gt;
        </button>
      </div>

      <div class="toolbar-divider"></div>

      <!-- 文字颜色 -->
      <div class="toolbar-group">
        <input
          type="color"
          :value="editor.getAttributes('textStyle').color || '#000000'"
          @input="editor.chain().focus().setColor($event.target.value).run()"
          title="文字颜色"
          class="color-picker"
        />
      </div>

      <div class="toolbar-divider"></div>

      <!-- 列表 -->
      <div class="toolbar-group">
        <button
          @click="editor.chain().focus().toggleBulletList().run()"
          :class="{ active: editor.isActive('bulletList') }"
          title="无序列表"
        >
          • 列表
        </button>
        <button
          @click="editor.chain().focus().toggleOrderedList().run()"
          :class="{ active: editor.isActive('orderedList') }"
          title="有序列表"
        >
          1. 列表
        </button>
        <button
          @click="editor.chain().focus().toggleTaskList().run()"
          :class="{ active: editor.isActive('taskList') }"
          title="任务列表"
        >
          ☑ 任务
        </button>
      </div>

      <div class="toolbar-divider"></div>

      <!-- 引用 & 代码块 -->
      <div class="toolbar-group">
        <button
          @click="editor.chain().focus().toggleBlockquote().run()"
          :class="{ active: editor.isActive('blockquote') }"
          title="引用"
        >
          引用
        </button>
        <button
          @click="editor.chain().focus().toggleCodeBlock().run()"
          :class="{ active: editor.isActive('codeBlock') }"
          title="代码块"
        >
          代码块
        </button>
      </div>

      <div class="toolbar-divider"></div>

      <!-- 插入 -->
      <div class="toolbar-group">
        <button @click="addImage" title="插入图片">
          🖼 图片
        </button>
        <button @click="setLink" title="插入链接">
          🔗 链接
        </button>
        <button
          @click="editor.chain().focus().setHorizontalRule().run()"
          title="分割线"
        >
          ── 分割线
        </button>
        <button @click="insertTable" title="插入表格">
          📊 表格
        </button>
      </div>

      <div class="toolbar-divider"></div>

      <!-- 撤销/重做 -->
      <div class="toolbar-group">
        <button
          @click="editor.chain().focus().undo().run()"
          :disabled="!editor.can().undo()"
          title="撤销 (Ctrl+Z)"
        >
          ↩ 撤销
        </button>
        <button
          @click="editor.chain().focus().redo().run()"
          :disabled="!editor.can().redo()"
          title="重做 (Ctrl+Shift+Z)"
        >
          ↪ 重做
        </button>
      </div>
    </div>

    <!-- 编辑区域 -->
    <editor-content :editor="editor" class="editor-content" />

    <!-- 底部状态栏 -->
    <div v-if="editor" class="status-bar">
      <span>{{ characterCount }} 字符</span>
      <span>{{ wordCount }} 词</span>
    </div>
  </div>
</template>

<script>
import { Editor, EditorContent } from '@tiptap/vue-2';
import StarterKit from '@tiptap/starter-kit';
import Image from '@tiptap/extension-image';
import Link from '@tiptap/extension-link';
import Placeholder from '@tiptap/extension-placeholder';
import CodeBlockLowlight from '@tiptap/extension-code-block-lowlight';
import TextStyle from '@tiptap/extension-text-style';
import Color from '@tiptap/extension-color';
import TaskList from '@tiptap/extension-task-list';
import TaskItem from '@tiptap/extension-task-item';
import Table from '@tiptap/extension-table';
import TableRow from '@tiptap/extension-table-row';
import TableCell from '@tiptap/extension-table-cell';
import TableHeader from '@tiptap/extension-table-header';
import CharacterCount from '@tiptap/extension-character-count';
import { lowlight } from 'lowlight';

export default {
  name: 'TiptapEditor',
  components: { EditorContent },

  props: {
    value: { type: String, default: '' },
    editable: { type: Boolean, default: true },
    maxLength: { type: Number, default: null },
  },

  data() {
    return {
      editor: null,
      isFocused: false,
    };
  },

  computed: {
    characterCount() {
      return this.editor?.storage.characterCount.characters() || 0;
    },
    wordCount() {
      return this.editor?.storage.characterCount.words() || 0;
    },
    currentHeading() {
      if (!this.editor) return 'paragraph';
      for (let i = 1; i <= 4; i++) {
        if (this.editor.isActive('heading', { level: i })) return String(i);
      }
      return 'paragraph';
    },
  },

  mounted() {
    this.editor = new Editor({
      // 内容
      content: this.value,

      // 是否可编辑
      editable: this.editable,

      // 扩展列表——Tiptap 的核心设计：一切皆扩展
      extensions: [
        // StarterKit 包含了基础扩展（段落、标题、加粗、斜体等）
        // 但我们要用 CodeBlockLowlight 替换默认的 codeBlock
        StarterKit.configure({
          codeBlock: false, // 禁用默认代码块，用高亮版替换
        }),

        // 图片
        Image.configure({
          inline: true,
          allowBase64: true,
          HTMLAttributes: {
            class: 'editor-image',
          },
        }),

        // 链接
        Link.configure({
          openOnClick: false, // 编辑模式下点击不跳转
          autolink: true,     // 自动识别URL
          linkOnPaste: true,  // 粘贴时自动转链接
          HTMLAttributes: {
            target: '_blank',
            rel: 'noopener noreferrer',
          },
        }),

        // 占位符
        Placeholder.configure({
          placeholder: '开始写作...',
        }),

        // 代码块 + 语法高亮
        CodeBlockLowlight.configure({
          lowlight,
          defaultLanguage: 'javascript',
        }),

        // 文字颜色
        TextStyle,
        Color,

        // 任务列表
        TaskList,
        TaskItem.configure({
          nested: true, // 支持嵌套
        }),

        // 表格
        Table.configure({
          resizable: true,
        }),
        TableRow,
        TableCell,
        TableHeader,

        // 字数统计
        CharacterCount.configure({
          limit: this.maxLength,
        }),
      ],

      // 事件回调
      onUpdate: ({ editor }) => {
        const html = editor.getHTML();
        this.$emit('input', html); // v-model 支持
        this.$emit('change', {
          html,
          json: editor.getJSON(),
          text: editor.getText(),
        });
      },

      onFocus: () => {
        this.isFocused = true;
        this.$emit('focus');
      },

      onBlur: () => {
        this.isFocused = false;
        this.$emit('blur');
      },

      onSelectionUpdate: ({ editor }) => {
        this.$emit('selection-change', editor);
      },
    });
  },

  methods: {
    // 设置标题级别
    setHeading(level) {
      if (level === 'paragraph') {
        this.editor.chain().focus().setParagraph().run();
      } else {
        this.editor
          .chain()
          .focus()
          .toggleHeading({ level: parseInt(level) })
          .run();
      }
    },

    // 插入图片
    addImage() {
      const url = window.prompt('请输入图片 URL：');
      if (url) {
        this.editor.chain().focus().setImage({ src: url }).run();
      }
    },

    // 文件上传方式插入图片
    async uploadImage(file) {
      const formData = new FormData();
      formData.append('file', file);
      try {
        const res = await fetch('/api/upload', {
          method: 'POST',
          body: formData,
        });
        const { url } = await res.json();
        this.editor.chain().focus().setImage({ src: url }).run();
      } catch (err) {
        console.error('图片上传失败:', err);
      }
    },

    // 设置链接
    setLink() {
      const previousUrl = this.editor.getAttributes('link').href;
      const url = window.prompt('请输入链接 URL：', previousUrl);

      if (url === null) return; // 取消
      if (url === '') {
        // 移除链接
        this.editor.chain().focus().extendMarkRange('link').unsetLink().run();
        return;
      }

      this.editor
        .chain()
        .focus()
        .extendMarkRange('link')
        .setLink({ href: url })
        .run();
    },

    // 插入表格
    insertTable() {
      this.editor
        .chain()
        .focus()
        .insertTable({ rows: 3, cols: 3, withHeaderRow: true })
        .run();
    },

    // 外部API：获取内容
    getContent() {
      return {
        html: this.editor.getHTML(),
        json: this.editor.getJSON(),
        text: this.editor.getText(),
      };
    },

    // 外部API：设置内容
    setContent(content) {
      this.editor.commands.setContent(content);
    },
  },

  watch: {
    value(newVal) {
      const currentHtml = this.editor.getHTML();
      if (newVal !== currentHtml) {
        this.editor.commands.setContent(newVal, false);
      }
    },
    editable(newVal) {
      this.editor.setEditable(newVal);
    },
  },

  beforeDestroy() {
    this.editor?.destroy();
  },
};
</script>

<style>
/* 编辑器外框 */
.tiptap-editor {
  border: 1px solid #d9d9d9;
  border-radius: 8px;
  overflow: hidden;
  transition: border-color 0.2s;
}
.tiptap-editor.focused {
  border-color: #1890ff;
  box-shadow: 0 0 0 2px rgba(24, 144, 255, 0.1);
}

/* 工具栏 */
.toolbar {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 2px;
  padding: 8px;
  border-bottom: 1px solid #e8e8e8;
  background: #fafafa;
}
.toolbar-group {
  display: flex;
  gap: 2px;
}
.toolbar-divider {
  width: 1px;
  height: 24px;
  background: #d9d9d9;
  margin: 0 6px;
}
.toolbar button {
  padding: 4px 8px;
  border: 1px solid transparent;
  border-radius: 4px;
  background: transparent;
  cursor: pointer;
  font-size: 13px;
  color: #333;
  transition: all 0.15s;
  white-space: nowrap;
}
.toolbar button:hover {
  background: #e6f7ff;
  border-color: #91d5ff;
}
.toolbar button.active {
  background: #1890ff;
  color: white;
  border-color: #1890ff;
}
.toolbar button:disabled {
  opacity: 0.4;
  cursor: not-allowed;
}
.toolbar-select {
  padding: 4px 8px;
  border: 1px solid #d9d9d9;
  border-radius: 4px;
  font-size: 13px;
  background: white;
  cursor: pointer;
}

.color-picker {
  width: 32px;
  height: 28px;
  border: 1px solid #d9d9d9;
  border-radius: 4px;
  padding: 2px;
  cursor: pointer;
  background: white;
}

/* 编辑区域 */
.editor-content {
  padding: 16px 20px;
  min-height: 300px;
  max-height: 600px;
  overflow-y: auto;
}

/* ============ Tiptap 内部内容样式（ProseMirror）============ */
/* 注意：这些样式不能加 scoped，因为是渲染在 .ProseMirror 内部的 */
.ProseMirror {
  outline: none;
  font-size: 15px;
  line-height: 1.75;
  color: #333;
}

.ProseMirror > * + * {
  margin-top: 0.75em;
}

/* 占位符 */
.ProseMirror p.is-editor-empty:first-child::before {
  color: #adb5bd;
  content: attr(data-placeholder);
  float: left;
  height: 0;
  pointer-events: none;
}

/* 标题 */
.ProseMirror h1 { font-size: 2em; font-weight: 700; margin-top: 1em; }
.ProseMirror h2 { font-size: 1.5em; font-weight: 700; margin-top: 0.8em; }
.ProseMirror h3 { font-size: 1.25em; font-weight: 600; margin-top: 0.6em; }
.ProseMirror h4 { font-size: 1.1em; font-weight: 600; margin-top: 0.5em; }

/* 引用 */
.ProseMirror blockquote {
  border-left: 4px solid #1890ff;
  padding-left: 16px;
  margin-left: 0;
  color: #666;
  background: #f9f9f9;
  padding: 12px 16px;
  border-radius: 0 4px 4px 0;
}

/* 代码块 */
.ProseMirror pre {
  background: #282c34;
  color: #abb2bf;
  border-radius: 8px;
  padding: 16px;
  overflow-x: auto;
  font-family: 'Fira Code', 'Consolas', monospace;
  font-size: 14px;
  line-height: 1.5;
}
.ProseMirror pre code {
  background: none;
  color: inherit;
  padding: 0;
}

/* 行内代码 */
.ProseMirror code {
  background: #f0f0f0;
  color: #d63384;
  padding: 2px 6px;
  border-radius: 3px;
  font-size: 0.9em;
}

/* 链接 */
.ProseMirror a {
  color: #1890ff;
  text-decoration: underline;
  cursor: pointer;
}

/* 图片 */
.ProseMirror img.editor-image {
  max-width: 100%;
  height: auto;
  border-radius: 4px;
  margin: 8px 0;
}

/* 任务列表 */
.ProseMirror ul[data-type="taskList"] {
  list-style: none;
  padding-left: 0;
}
.ProseMirror ul[data-type="taskList"] li {
  display: flex;
  align-items: flex-start;
  gap: 8px;
}
.ProseMirror ul[data-type="taskList"] li label {
  margin-top: 3px;
}
.ProseMirror ul[data-type="taskList"] li[data-checked="true"] > div > p {
  text-decoration: line-through;
  color: #999;
}

/* 表格 */
.ProseMirror table {
  border-collapse: collapse;
  width: 100%;
  margin: 12px 0;
}
.ProseMirror th,
.ProseMirror td {
  border: 1px solid #d9d9d9;
  padding: 8px 12px;
  text-align: left;
  min-width: 80px;
}
.ProseMirror th {
  background: #fafafa;
  font-weight: 600;
}
.ProseMirror .selectedCell {
  background: #e6f7ff;
}

/* 分割线 */
.ProseMirror hr {
  border: none;
  border-top: 2px solid #e8e8e8;
  margin: 20px 0;
}

/* 状态栏 */
.status-bar {
  display: flex;
  gap: 16px;
  padding: 6px 16px;
  border-top: 1px solid #e8e8e8;
  background: #fafafa;
  font-size: 12px;
  color: #999;
}
</style>

3.3 Tiptap 自定义扩展：@提及（Mention）

这是 Tiptap 最强大的能力——自定义 Node/Mark 扩展：

src/extensions/MentionExtension.js

import { Node, mergeAttributes } from '@tiptap/core';
import { VueRenderer } from '@tiptap/vue-2';
import tippy from 'tippy.js';
import MentionList from './MentionList.vue';

/**
 * 自定义 Mention 扩展
 * 输入 @ 后弹出用户列表，选择后插入 @用户名 标签
 */
export default Node.create({
  name: 'mention',

  // 定义为行内元素、void 元素（不可编辑内部内容）
  group: 'inline',
  inline: true,
  selectable: false,
  atom: true, // 作为一个原子节点（整体选中/删除）

  // 定义该节点的属性
  addAttributes() {
    return {
      id: {
        default: null,
        parseHTML: (element) => element.getAttribute('data-mention-id'),
        renderHTML: (attributes) => ({
          'data-mention-id': attributes.id,
        }),
      },
      label: {
        default: null,
        parseHTML: (element) => element.getAttribute('data-mention-label'),
        renderHTML: (attributes) => ({
          'data-mention-label': attributes.label,
        }),
      },
    };
  },

  // 从 HTML 解析
  parseHTML() {
    return [
      {
        tag: 'span[data-type="mention"]',
      },
    ];
  },

  // 渲染为 HTML
  renderHTML({ node, HTMLAttributes }) {
    return [
      'span',
      mergeAttributes(
        {
          'data-type': 'mention',
          class: 'mention-tag',
        },
        HTMLAttributes
      ),
      `@${node.attrs.label}`,
    ];
  },

  // 渲染为文本（用于 getText()）
  renderText({ node }) {
    return `@${node.attrs.label}`;
  },

  // 添加输入建议（核心：@ 触发）
  addProseMirrorPlugins() {
    const editor = this.editor;

    return [
      // 使用 ProseMirror 插件监听输入
      createMentionPlugin({
        editor,
        char: '@', // 触发字符
        // 查询用户列表的函数
        items: async (query) => {
          // 这里可以调用 API 搜索用户
          const allUsers = [
            { id: 1, name: '张三', avatar: '👤' },
            { id: 2, name: '李四', avatar: '👤' },
            { id: 3, name: '王五', avatar: '👤' },
            { id: 4, name: '赵六', avatar: '👤' },
            { id: 5, name: 'Admin', avatar: '👑' },
          ];

          return allUsers
            .filter((user) =>
              user.name.toLowerCase().includes(query.toLowerCase())
            )
            .slice(0, 5);
        },
        // 渲染下拉列表
        render: () => {
          let component;
          let popup;

          return {
            onStart: (props) => {
              component = new VueRenderer(MentionList, {
                parent: this,
                propsData: props,
              });

              popup = tippy('body', {
                getReferenceClientRect: props.clientRect,
                appendTo: () => document.body,
                content: component.element,
                showOnCreate: true,
                interactive: true,
                trigger: 'manual',
                placement: 'bottom-start',
              });
            },

            onUpdate: (props) => {
              component.updateProps(props);
              popup[0].setProps({
                getReferenceClientRect: props.clientRect,
              });
            },

            onKeyDown: (props) => {
              if (props.event.key === 'Escape') {
                popup[0].hide();
                return true;
              }
              return component.ref?.onKeyDown(props.event);
            },

            onExit: () => {
              popup[0].destroy();
              component.destroy();
            },
          };
        },
      }),
    ];
  },
});

/**
 * 创建 Mention 的 ProseMirror 插件（简化版）
 */
function createMentionPlugin({ editor, char, items, render }) {
  const { Plugin, PluginKey } = require('prosemirror-state');

  return new Plugin({
    key: new PluginKey('mention'),

    state: {
      init() {
        return { active: false, query: '', range: null };
      },
      apply(tr, prev) {
        const meta = tr.getMeta('mention');
        if (meta) return meta;
        if (tr.docChanged) return { active: false, query: '', range: null };
        return prev;
      },
    },

    view() {
      let rendererInstance = null;

      return {
        update: async (view, prevState) => {
          const { state } = view;
          const { selection } = state;
          const { $from } = selection;

          // 检测光标前是否有 @ 字符
          const textBefore = $from.parent.textContent.slice(0, $from.parentOffset);
          const match = textBefore.match(new RegExp(`\\${char}([\\w\\u4e00-\\u9fa5]*)$`));

          if (!match) {
            if (rendererInstance) {
              rendererInstance.onExit();
              rendererInstance = null;
            }
            return;
          }

          const query = match[1];
          const from = $from.pos - query.length - 1;
          const to = $from.pos;

          const matchedItems = await items(query);

          const props = {
            editor,
            query,
            items: matchedItems,
            clientRect: () => {
              const coords = view.coordsAtPos(from);
              return new DOMRect(coords.left, coords.top, 0, coords.bottom - coords.top);
            },
            command: (item) => {
              editor
                .chain()
                .focus()
                .deleteRange({ from, to })
                .insertContent({
                  type: 'mention',
                  attrs: { id: item.id, label: item.name },
                })
                .insertContent(' ')
                .run();
            },
          };

          if (!rendererInstance) {
            rendererInstance = render();
            rendererInstance.onStart(props);
          } else {
            rendererInstance.onUpdate(props);
          }
        },

        destroy() {
          if (rendererInstance) {
            rendererInstance.onExit();
          }
        },
      };
    },
  });
}

src/extensions/MentionList.vue

<template>
  <div class="mention-list">
    <div
      v-for="(item, index) in items"
      :key="item.id"
      class="mention-item"
      :class="{ selected: index === selectedIndex }"
      @click="selectItem(index)"
      @mouseenter="selectedIndex = index"
    >
      <span class="avatar">{{ item.avatar }}</span>
      <span class="name">{{ item.name }}</span>
    </div>
    <div v-if="!items.length" class="mention-empty">
      未找到匹配用户
    </div>
  </div>
</template>

<script>
export default {
  name: 'MentionList',
  props: {
    items: { type: Array, required: true },
    command: { type: Function, required: true },
  },

  data() {
    return { selectedIndex: 0 };
  },

  watch: {
    items() {
      this.selectedIndex = 0;
    },
  },

  methods: {
    onKeyDown(event) {
      if (event.key === 'ArrowUp') {
        this.selectedIndex =
          (this.selectedIndex - 1 + this.items.length) % this.items.length;
        return true;
      }
      if (event.key === 'ArrowDown') {
        this.selectedIndex = (this.selectedIndex + 1) % this.items.length;
        return true;
      }
      if (event.key === 'Enter') {
        this.selectItem(this.selectedIndex);
        return true;
      }
      return false;
    },

    selectItem(index) {
      const item = this.items[index];
      if (item) {
        this.command(item);
      }
    },
  },
};
</script>

<style scoped>
.mention-list {
  background: white;
  border: 1px solid #e8e8e8;
  border-radius: 8px;
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
  padding: 4px;
  min-width: 180px;
}
.mention-item {
  display: flex;
  align-items: center;
  gap: 8px;
  padding: 8px 12px;
  border-radius: 4px;
  cursor: pointer;
  transition: background 0.1s;
}
.mention-item.selected,
.mention-item:hover {
  background: #e6f7ff;
}
.avatar {
  font-size: 18px;
}
.name {
  font-size: 14px;
  color: #333;
}
.mention-empty {
  padding: 12px;
  text-align: center;
  color: #999;
  font-size: 13px;
}
</style>

3.4 Slate.js (React) —— 极致灵活的底层框架

适用场景： 高度自定义编辑器（类 Notion、飞书文档）

安装

npm install slate slate-react slate-history

完整示例

import React, { useState, useCallback, useMemo } from 'react';
import { createEditor, Editor, Transforms, Text, Element as SlateElement } from 'slate';
import { Slate, Editable, withReact, useSlate, useSelected, useFocused } from 'slate-react';
import { withHistory } from 'slate-history';

// ============ 1. 自定义元素渲染 ============

/**
 * Slate 的核心理念：你完全控制每个节点如何渲染
 * 通过 renderElement 和 renderLeaf 两个函数
 */
const RenderElement = ({ attributes, children, element }) => {
  // attributes 必须展开到最外层 DOM
  // children 必须作为子节点渲染
  switch (element.type) {
    case 'heading-one':
      return <h1 {...attributes} style={{ fontSize: '2em', fontWeight: 700, marginTop: '0.5em' }}>{children}</h1>;

    case 'heading-two':
      return <h2 {...attributes} style={{ fontSize: '1.5em', fontWeight: 700, marginTop: '0.4em' }}>{children}</h2>;

    case 'heading-three':
      return <h3 {...attributes} style={{ fontSize: '1.25em', fontWeight: 600 }}>{children}</h3>;

    case 'blockquote':
      return (
        <blockquote
          {...attributes}
          style={{
            borderLeft: '4px solid #1890ff',
            paddingLeft: 16,
            color: '#666',
            background: '#f9f9f9',
            padding: '12px 16px',
            borderRadius: '0 4px 4px 0',
            margin: '8px 0',
          }}
        >
          {children}
        </blockquote>
      );

    case 'code-block':
      return (
        <pre
          {...attributes}
          style={{
            background: '#282c34',
            color: '#abb2bf',
            padding: 16,
            borderRadius: 8,
            fontFamily: "'Fira Code', monospace",
            fontSize: 14,
            overflow: 'auto',
          }}
        >
          <code>{children}</code>
        </pre>
      );

    case 'bulleted-list':
      return <ul {...attributes} style={{ paddingLeft: 24 }}>{children}</ul>;

    case 'numbered-list':
      return <ol {...attributes} style={{ paddingLeft: 24 }}>{children}</ol>;

    case 'list-item':
      return <li {...attributes}>{children}</li>;

    case 'image':
      return <ImageElement attributes={attributes} element={element}>{children}</ImageElement>;

    case 'divider':
      return (
        <div {...attributes} contentEditable={false} style={{ margin: '20px 0' }}>
          <hr style={{ border: 'none', borderTop: '2px solid #e8e8e8' }} />
          {children}
        </div>
      );

    default:
      return <p {...attributes} style={{ marginBottom: '0.5em', lineHeight: 1.75 }}>{children}</p>;
  }
};

/**
 * 叶子节点渲染（处理文本级别的格式：加粗、斜体、颜色等）
 */
const RenderLeaf = ({ attributes, children, leaf }) => {
  let el = children;

  if (leaf.bold) {
    el = <strong>{el}</strong>;
  }
  if (leaf.italic) {
    el = <em>{el}</em>;
  }
  if (leaf.underline) {
    el = <u>{el}</u>;
  }
  if (leaf.strikethrough) {
    el = <s>{el}</s>;
  }
  if (leaf.code) {
    el = (
      <code
        style={{
          background: '#f0f0f0',
          color: '#d63384',
          padding: '2px 6px',
          borderRadius: 3,
          fontSize: '0.9em',
        }}
      >
        {el}
      </code>
    );
  }
  if (leaf.color) {
    el = <span style={{ color: leaf.color }}>{el}</span>;
  }

  return <span {...attributes}>{el}</span>;
};

// ============ 2. 图片元素组件（Void 元素） ============

const ImageElement = ({ attributes, children, element }) => {
  const selected = useSelected();
  const focused = useFocused();

  return (
    <div {...attributes} contentEditable={false}>
      <img
        src={element.url}
        alt={element.alt || ''}
        style={{
          display: 'block',
          maxWidth: '100%',
          borderRadius: 4,
          boxShadow: selected && focused ? '0 0 0 3px #1890ff' : 'none',
          margin: '8px 0',
        }}
      />
      {children}
    </div>
  );
};

// ============ 3. 工具栏组件 ============

const Toolbar = () => {
  const editor = useSlate(); // 获取编辑器实例

  return (
    <div style={{
      display: 'flex',
      flexWrap: 'wrap',
      gap: 2,
      padding: 8,
      borderBottom: '1px solid #e8e8e8',
      background: '#fafafa',
    }}>
      {/* 文本格式 */}
      <MarkButton format="bold" label="B" style={{ fontWeight: 700 }} />
      <MarkButton format="italic" label="I" style={{ fontStyle: 'italic' }} />
      <MarkButton format="underline" label="U" style={{ textDecoration: 'underline' }} />
      <MarkButton format="strikethrough" label="S" style={{ textDecoration: 'line-through' }} />
      <MarkButton format="code" label="</>" />

      <Divider />

      {/* 块级格式 */}
      <BlockButton format="heading-one" label="H1" />
      <BlockButton format="heading-two" label="H2" />
      <BlockButton format="heading-three" label="H3" />
      <BlockButton format="blockquote" label="引用" />
      <BlockButton format="code-block" label="代码块" />

      <Divider />

      {/* 列表 */}
      <BlockButton format="bulleted-list" label="• 列表" />
      <BlockButton format="numbered-list" label="1. 列表" />

      <Divider />

      {/* 插入 */}
      <InsertImageButton />
      <InsertDividerButton />
    </div>
  );
};

const Divider = () => (
  <span style={{
    width: 1, height: 24, background: '#d9d9d9', margin: '0 6px', alignSelf: 'center',
  }} />
);

// ============ 4. 工具栏按钮组件 ============

/**
 * Mark按钮（文本级格式：加粗、斜体等）
 */
const MarkButton = ({ format, label, style = {} }) => {
  const editor = useSlate();
  const isActive = isMarkActive(editor, format);

  return (
    <button
      style={{
        padding: '4px 8px',
        border: '1px solid transparent',
        borderRadius: 4,
        background: isActive ? '#1890ff' : 'transparent',
        color: isActive ? 'white' : '#333',
        cursor: 'pointer',
        fontSize: 13,
        ...style,
      }}
      onMouseDown={(e) => {
        e.preventDefault(); // 防止失去焦点
        toggleMark(editor, format);
      }}
    >
      {label}
    </button>
  );
};

/**
 * Block按钮（块级格式：标题、引用等）
 */
const BlockButton = ({ format, label }) => {
  const editor = useSlate();
  const isActive = isBlockActive(editor, format);

  return (
    <button
      style={{
        padding: '4px 8px',
        border: '1px solid transparent',
        borderRadius: 4,
        background: isActive ? '#1890ff' : 'transparent',
        color: isActive ? 'white' : '#333',
        cursor: 'pointer',
        fontSize: 13,
      }}
      onMouseDown={(e) => {
        e.preventDefault();
        toggleBlock(editor, format);
      }}
    >
      {label}
    </button>
  );
};

/**
 * 插入图片按钮
 */
const InsertImageButton = () => {
  const editor = useSlate();

  return (
    <button
      style={{
        padding: '4px 8px', border: '1px solid transparent',
        borderRadius: 4, cursor: 'pointer', fontSize: 13,
      }}
      onMouseDown={(e) => {
        e.preventDefault();
        const url = window.prompt('请输入图片URL：');
        if (url) {
          insertImage(editor, url);
        }
      }}
    >
      🖼 图片
    </button>
  );
};

/**
 * 插入分割线按钮
 */
const InsertDividerButton = () => {
  const editor = useSlate();

  return (
    <button
      style={{
        padding: '4px 8px', border: '1px solid transparent',
        borderRadius: 4, cursor: 'pointer', fontSize: 13,
      }}
      onMouseDown={(e) => {
        e.preventDefault();
        Transforms.insertNodes(editor, {
          type: 'divider',
          children: [{ text: '' }],
        });
        // 在分割线后插入空段落
        Transforms.insertNodes(editor, {
          type: 'paragraph',
          children: [{ text: '' }],
        });
      }}
    >
      ── 分割线
    </button>
  );
};

// ============ 5. 编辑器操作工具函数 ============

const LIST_TYPES = ['bulleted-list', 'numbered-list'];

/**
 * 检查 Mark 是否激活
 */
function isMarkActive(editor, format) {
  const marks = Editor.marks(editor);
  return marks ? marks[format] === true : false;
}

/**
 * 切换 Mark
 */
function toggleMark(editor, format) {
  const isActive = isMarkActive(editor, format);
  if (isActive) {
    Editor.removeMark(editor, format);
  } else {
    Editor.addMark(editor, format, true);
  }
}

/**
 * 检查 Block 是否激活
 */
function isBlockActive(editor, format) {
  const [match] = Editor.nodes(editor, {
    match: (n) =>
      !Editor.isEditor(n) &&
      SlateElement.isElement(n) &&
      n.type === format,
  });
  return !!match;
}

/**
 * 切换 Block 类型
 */
function toggleBlock(editor, format) {
  const isActive = isBlockActive(editor, format);
  const isList = LIST_TYPES.includes(format);

  // 先解除所有列表包裹
  Transforms.unwrapNodes(editor, {
    match: (n) =>
      !Editor.isEditor(n) &&
      SlateElement.isElement(n) &&
      LIST_TYPES.includes(n.type),
    split: true,
  });

  // 设置节点类型
  Transforms.setNodes(editor, {
    type: isActive ? 'paragraph' : isList ? 'list-item' : format,
  });

  // 如果是列表，需要包裹
  if (!isActive && isList) {
    Transforms.wrapNodes(editor, {
      type: format,
      children: [],
    });
  }
}

/**
 * 插入图片
 */
function insertImage(editor, url) {
  const image = { type: 'image', url, children: [{ text: '' }] };
  Transforms.insertNodes(editor, image);
  // 在图片后插入空段落
  Transforms.insertNodes(editor, {
    type: 'paragraph',
    children: [{ text: '' }],
  });
}

// ============ 6. 自定义 withInlines 插件 ============

/**
 * 告诉编辑器哪些是 Void 元素（不可编辑内部内容的）
 */
function withCustomElements(editor) {
  const { isVoid, isInline } = editor;

  editor.isVoid = (element) => {
    return ['image', 'divider'].includes(element.type)
      ? true
      : isVoid(element);
  };

  return editor;
}

// ============ 7. 主组件 ============

const initialValue = [
  {
    type: 'heading-one',
    children: [{ text: 'Slate.js 富文本编辑器' }],
  },
  {
    type: 'paragraph',
    children: [
      { text: '这是一个' },
      { text: '完全自定义', bold: true },
      { text: '的富文本编辑器。Slate 让你控制' },
      { text: '每一个细节', italic: true, color: '#1890ff' },
      { text: '。' },
    ],
  },
  {
    type: 'blockquote',
    children: [{ text: 'Slate 的理念：提供构建编辑器的积木，而不是一个完整的编辑器。' }],
  },
  {
    type: 'code-block',
    children: [{ text: 'const editor = useMemo(\n  () => withCustomElements(withHistory(withReact(createEditor()))),\n  []\n);' }],
  },
  {
    type: 'paragraph',
    children: [{ text: '' }],
  },
];

export default function SlateEditor() {
  // 创建编辑器实例（useMemo 确保只创建一次）
  const editor = useMemo(
    () => withCustomElements(withHistory(withReact(createEditor()))),
    []
  );

  const [value, setValue] = useState(initialValue);

  const renderElement = useCallback((props) => <RenderElement {...props} />, []);
  const renderLeaf = useCallback((props) => <RenderLeaf {...props} />, []);

  // 快捷键处理
  const handleKeyDown = useCallback(
    (event) => {
      // Ctrl/Cmd + B = 加粗
      if (event.ctrlKey || event.metaKey) {
        switch (event.key) {
          case 'b':
            event.preventDefault();
            toggleMark(editor, 'bold');
            break;
          case 'i':
            event.preventDefault();
            toggleMark(editor, 'italic');
            break;
          case 'u':
            event.preventDefault();
            toggleMark(editor, 'underline');
            break;
          case '`':
            event.preventDefault();
            toggleMark(editor, 'code');
            break;
          default:
            break;
        }
      }

      // Markdown 快捷输入（在行首输入特定字符后按空格触发）
      if (event.key === ' ') {
        const { selection } = editor;
        if (selection && selection.anchor.offset > 0) {
          const [node] = Editor.node(editor, selection);
          if (Text.isText(node)) {
            const textBeforeCursor = node.text.slice(0, selection.anchor.offset);

            // # + 空格 = H1
            if (textBeforeCursor === '#') {
              event.preventDefault();
              Transforms.delete(editor, {
                at: {
                  anchor: { ...selection.anchor, offset: 0 },
                  focus: selection.anchor,
                },
              });
              toggleBlock(editor, 'heading-one');
              return;
            }
            // ## + 空格 = H2
            if (textBeforeCursor === '##') {
              event.preventDefault();
              Transforms.delete(editor, {
                at: {
                  anchor: { ...selection.anchor, offset: 0 },
                  focus: selection.anchor,
                },
              });
              toggleBlock(editor, 'heading-two');
              return;
            }
            // ### + 空格 = H3
            if (textBeforeCursor === '###') {
              event.preventDefault();
              Transforms.delete(editor, {
                at: {
                  anchor: { ...selection.anchor, offset: 0 },
                  focus: selection.anchor,
                },
              });
              toggleBlock(editor, 'heading-three');
              return;
            }
            // > + 空格 = 引用
            if (textBeforeCursor === '>') {
              event.preventDefault();
              Transforms.delete(editor, {
                at: {
                  anchor: { ...selection.anchor, offset: 0 },
                  focus: selection.anchor,
                },
              });
              toggleBlock(editor, 'blockquote');
              return;
            }
            // - 或 * + 空格 = 无序列表
            if (textBeforeCursor === '-' || textBeforeCursor === '*') {
              event.preventDefault();
              Transforms.delete(editor, {
                at: {
                  anchor: { ...selection.anchor, offset: 0 },
                  focus: selection.anchor,
                },
              });
              toggleBlock(editor, 'bulleted-list');
              return;
            }
            // 1. + 空格 = 有序列表
            if (/^\d+\.$/.test(textBeforeCursor)) {
              event.preventDefault();
              Transforms.delete(editor, {
                at: {
                  anchor: { ...selection.anchor, offset: 0 },
                  focus: selection.anchor,
                },
              });
              toggleBlock(editor, 'numbered-list');
              return;
            }
            // ``` + 空格 = 代码块
            if (textBeforeCursor === '```') {
              event.preventDefault();
              Transforms.delete(editor, {
                at: {
                  anchor: { ...selection.anchor, offset: 0 },
                  focus: selection.anchor,
                },
              });
              toggleBlock(editor, 'code-block');
              return;
            }
          }
        }
      }

      // Enter 在代码块中：插入换行而不是新段落
      if (event.key === 'Enter' && !event.shiftKey) {
        const [codeBlock] = Editor.nodes(editor, {
          match: (n) => SlateElement.isElement(n) && n.type === 'code-block',
        });
        if (codeBlock) {
          event.preventDefault();
          editor.insertText('\n');
          return;
        }
      }
    },
    [editor]
  );

  return (
    <div style={{
      border: '1px solid #d9d9d9',
      borderRadius: 8,
      overflow: 'hidden',
      maxWidth: 800,
      margin: '40px auto',
    }}>
      <Slate
        editor={editor}
        value={value}
        onChange={(newValue) => {
          setValue(newValue);

          // 检查内容是否真的变了（排除纯选区变化）
          const isContentChange = editor.operations.some(
            (op) => op.type !== 'set_selection'
          );
          if (isContentChange) {
            // 自动保存、同步等
            console.log('内容变化:', JSON.stringify(newValue));
          }
        }}
      >
        <Toolbar />
        <div style={{ padding: '16px 20px', minHeight: 300 }}>
          <Editable
            renderElement={renderElement}
            renderLeaf={renderLeaf}
            onKeyDown={handleKeyDown}
            placeholder="开始写作...（支持 Markdown 快捷输入）"
            spellCheck
            autoFocus
            style={{
              outline: 'none',
              fontSize: 15,
              lineHeight: 1.75,
            }}
          />
        </div>

        {/* 底部状态栏 */}
        <StatusBar />
      </Slate>
    </div>
  );
}

/**
 * 状态栏组件
 */
const StatusBar = () => {
  const editor = useSlate();

  const getStats = () => {
    const text = Editor.string(editor, []);
    return {
      chars: text.length,
      words: text.trim() ? text.trim().split(/\s+/).length : 0,
      blocks: editor.children.length,
    };
  };

  const stats = getStats();

  return (
    <div style={{
      display: 'flex',
      gap: 16,
      padding: '6px 16px',
      borderTop: '1px solid #e8e8e8',
      background: '#fafafa',
      fontSize: 12,
      color: '#999',
    }}>
      <span>{stats.chars} 字符</span>
      <span>{stats.words} 词</span>
      <span>{stats.blocks} 块</span>
    </div>
  );
};

Slate.js 序列化：JSON ↔ HTML 互转

// serializer.js

import { Text } from 'slate';
import escapeHtml from 'escape-html';

/**
 * Slate JSON → HTML
 */
export function slateToHtml(nodes) {
  return nodes.map((node) => serializeNode(node)).join('');
}

function serializeNode(node) {
  // 文本节点
  if (Text.isText(node)) {
    let text = escapeHtml(node.text);
    if (node.bold) text = `<strong>${text}</strong>`;
    if (node.italic) text = `<em>${text}</em>`;
    if (node.underline) text = `<u>${text}</u>`;
    if (node.strikethrough) text = `<s>${text}</s>`;
    if (node.code) text = `<code>${text}</code>`;
    if (node.color) text = `<span style="color:${node.color}">${text}</span>`;
    return text;
  }

  // 元素节点
  const children = node.children.map((n) => serializeNode(n)).join('');

  switch (node.type) {
    case 'heading-one':
      return `<h1>${children}</h1>`;
    case 'heading-two':
      return `<h2>${children}</h2>`;
    case 'heading-three':
      return `<h3>${children}</h3>`;
    case 'blockquote':
      return `<blockquote>${children}</blockquote>`;
    case 'code-block':
      return `<pre><code>${children}</code></pre>`;
    case 'bulleted-list':
      return `<ul>${children}</ul>`;
    case 'numbered-list':
      return `<ol>${children}</ol>`;
    case 'list-item':
      return `<li>${children}</li>`;
    case 'image':
      return `<img src="${escapeHtml(node.url)}" alt="${escapeHtml(node.alt || '')}" />`;
    case 'divider':
      return '<hr />';
    case 'paragraph':
    default:
      return `<p>${children}</p>`;
  }
}

/**
 * HTML → Slate JSON（简化版，生产环境建议用 slate-html-serializer）
 */
export function htmlToSlate(html) {
  const parser = new DOMParser();
  const doc = parser.parseFromString(html, 'text/html');
  return deserializeElement(doc.body);
}

function deserializeElement(el) {
  if (el.nodeType === Node.TEXT_NODE) {
    return [{ text: el.textContent }];
  }

  const children = Array.from(el.childNodes)
    .flatMap((child) => deserializeElement(child))
    .filter(Boolean);

  if (children.length === 0) {
    children.push({ text: '' });
  }

  switch (el.nodeName) {
    case 'BODY':
      return children;
    case 'H1':
      return [{ type: 'heading-one', children }];
    case 'H2':
      return [{ type: 'heading-two', children }];
    case 'H3':
      return [{ type: 'heading-three', children }];
    case 'BLOCKQUOTE':
      return [{ type: 'blockquote', children }];
    case 'PRE':
      return [{ type: 'code-block', children: [{ text: el.textContent }] }];
    case 'UL':
      return [{ type: 'bulleted-list', children }];
    case 'OL':
      return [{ type: 'numbered-list', children }];
    case 'LI':
      return [{ type: 'list-item', children }];
    case 'P':
      return [{ type: 'paragraph', children }];
    case 'IMG':
      return [{ type: 'image', url: el.src, children: [{ text: '' }] }];
    case 'HR':
      return [{ type: 'divider', children: [{ text: '' }] }];
    case 'STRONG':
    case 'B':
      return children.map((child) => ({ ...child, bold: true }));
    case 'EM':
    case 'I':
      return children.map((child) => ({ ...child, italic: true }));
    case 'U':
      return children.map((child) => ({ ...child, underline: true }));
    case 'S':
    case 'DEL':
      return children.map((child) => ({ ...child, strikethrough: true }));
    case 'CODE':
      return children.map((child) => ({ ...child, code: true }));
    default:
      return children;
  }
}

3.5 Lexical (React) —— Meta 出品的新一代编辑器

适用场景： 高性能、大文档、Meta 技术栈

安装

npm install lexical @lexical/react @lexical/rich-text @lexical/list \
  @lexical/link @lexical/code @lexical/table @lexical/utils \
  @lexical/selection @lexical/html

完整示例

import React, { useCallback } from 'react';
import { LexicalComposer } from '@lexical/react/LexicalComposer';
import { RichTextPlugin } from '@lexical/react/LexicalRichTextPlugin';
import { ContentEditable } from '@lexical/react/LexicalContentEditable';
import { HistoryPlugin } from '@lexical/react/LexicalHistoryPlugin';
import { OnChangePlugin } from '@lexical/react/LexicalOnChangePlugin';
import { ListPlugin } from '@lexical/react/LexicalListPlugin';
import { LinkPlugin } from '@lexical/react/LexicalLinkPlugin';
import { MarkdownShortcutPlugin } from '@lexical/react/LexicalMarkdownShortcutPlugin';
import LexicalErrorBoundary from '@lexical/react/LexicalErrorBoundary';
import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext';

// 节点类型
import { HeadingNode, QuoteNode } from '@lexical/rich-text';
import { ListNode, ListItemNode } from '@lexical/list';
import { LinkNode, AutoLinkNode } from '@lexical/link';
import { CodeNode, CodeHighlightNode } from '@lexical/code';
import { TableNode, TableCellNode, TableRowNode } from '@lexical/table';

// 格式化命令
import {
  FORMAT_TEXT_COMMAND,
  FORMAT_ELEMENT_COMMAND,
  UNDO_COMMAND,
  REDO_COMMAND,
  $getSelection,
  $isRangeSelection,
  $createParagraphNode,
} from 'lexical';
import { $createHeadingNode, $isHeadingNode } from '@lexical/rich-text';
import { $createQuoteNode } from '@lexical/rich-text';
import {
  INSERT_ORDERED_LIST_COMMAND,
  INSERT_UNORDERED_LIST_COMMAND,
  REMOVE_LIST_COMMAND,
} from '@lexical/list';
import { $generateHtmlFromNodes, $generateNodesFromDOM } from '@lexical/html';
import { TRANSFORMERS } from '@lexical/markdown';

// ============ 编辑器配置 ============

const editorConfig = {
  namespace: 'MyLexicalEditor',

  // 主题样式映射
  theme: {
    paragraph: 'editor-paragraph',
    heading: {
      h1: 'editor-h1',
      h2: 'editor-h2',
      h3: 'editor-h3',
    },
    text: {
      bold: 'editor-bold',
      italic: 'editor-italic',
      underline: 'editor-underline',
      strikethrough: 'editor-strikethrough',
      code: 'editor-code-inline',
    },
    quote: 'editor-quote',
    code: 'editor-code-block',
    list: {
      ul: 'editor-ul',
      ol: 'editor-ol',
      listitem: 'editor-li',
    },
    link: 'editor-link',
  },

  // 注册所有用到的节点类型
  nodes: [
    HeadingNode,
    QuoteNode,
    ListNode,
    ListItemNode,
    LinkNode,
    AutoLinkNode,
    CodeNode,
    CodeHighlightNode,
    TableNode,
    TableCellNode,
    TableRowNode,
  ],

  onError(error) {
    console.error('Lexical Error:', error);
  },
};

// ============ 工具栏插件 ============

function ToolbarPlugin() {
  const [editor] = useLexicalComposerContext();
  const [activeFormats, setActiveFormats] = React.useState({
    bold: false,
    italic: false,
    underline: false,
    strikethrough: false,
    code: false,
  });
  const [blockType, setBlockType] = React.useState('paragraph');

  // 监听选区变化，更新工具栏状态
  React.useEffect(() => {
    return editor.registerUpdateListener(({ editorState }) => {
      editorState.read(() => {
        const selection = $getSelection();
        if ($isRangeSelection(selection)) {
          setActiveFormats({
            bold: selection.hasFormat('bold'),
            italic: selection.hasFormat('italic'),
            underline: selection.hasFormat('underline'),
            strikethrough: selection.hasFormat('strikethrough'),
            code: selection.hasFormat('code'),
          });

          // 检查块级类型
          const anchorNode = selection.anchor.getNode();
          const parent = anchorNode.getParent();
          if ($isHeadingNode(parent)) {
            setBlockType(parent.getTag()); // 'h1', 'h2', 'h3'
          } else {
            setBlockType(parent?.getType?.() || 'paragraph');
          }
        }
      });
    });
  }, [editor]);

  // 格式化文本
  const formatText = (format) => {
    editor.dispatchCommand(FORMAT_TEXT_COMMAND, format);
  };

  // 设置块类型
  const formatBlock = (type) => {
    editor.update(() => {
      const selection = $getSelection();
      if ($isRangeSelection(selection)) {
        switch (type) {
          case 'h1':
            // 如果当前已经是 h1，切回段落
            if (blockType === 'h1') {
              selection.getNodes().forEach((node) => {
                if ($isHeadingNode(node)) {
                  node.replace($createParagraphNode());
                }
              });
            } else {
              const heading = $createHeadingNode('h1');
              selection.insertNodes([heading]);
            }
            break;
          case 'h2': {
            const heading = $createHeadingNode('h2');
            selection.insertNodes([heading]);
            break;
          }
          case 'h3': {
            const heading = $createHeadingNode('h3');
            selection.insertNodes([heading]);
            break;
          }
          case 'quote': {
            const quote = $createQuoteNode();
            selection.insertNodes([quote]);
            break;
          }
          default:
            break;
        }
      }
    });
  };

  const btnStyle = (active) => ({
    padding: '4px 8px',
    border: '1px solid transparent',
    borderRadius: 4,
    background: active ? '#1890ff' : 'transparent',
    color: active ? 'white' : '#333',
    cursor: 'pointer',
    fontSize: 13,
  });

  return (
    <div style={{
      display: 'flex',
      flexWrap: 'wrap',
      gap: 2,
      padding: 8,
      borderBottom: '1px solid #e8e8e8',
      background: '#fafafa',
    }}>
      {/* 文本格式 */}
      <button style={btnStyle(activeFormats.bold)}
        onClick={() => formatText('bold')}>
        <strong>B</strong>
      </button>
      <button style={btnStyle(activeFormats.italic)}
        onClick={() => formatText('italic')}>
        <em>I</em>
      </button>
      <button style={btnStyle(activeFormats.underline)}
        onClick={() => formatText('underline')}>
        <u>U</u>
      </button>
      <button style={btnStyle(activeFormats.strikethrough)}
        onClick={() => formatText('strikethrough')}>
        <s>S</s>
      </button>
      <button style={btnStyle(activeFormats.code)}
        onClick={() => formatText('code')}>
        {'</>'}
      </button>

      <span style={{ width: 1, height: 24, background: '#d9d9d9', margin: '0 6px', alignSelf: 'center' }} />

      {/* 块级格式 */}
      <button style={btnStyle(blockType === 'h1')}
        onClick={() => formatBlock('h1')}>H1</button>
      <button style={btnStyle(blockType === 'h2')}
        onClick={() => formatBlock('h2')}>H2</button>
      <button style={btnStyle(blockType === 'h3')}
        onClick={() => formatBlock('h3')}>H3</button>
      <button style={btnStyle(blockType === 'quote')}
        onClick={() => formatBlock('quote')}>引用</button>

      <span style={{ width: 1, height: 24, background: '#d9d9d9', margin: '0 6px', alignSelf: 'center' }} />

      {/* 列表 */}
      <button style={btnStyle(false)}
        onClick={() => editor.dispatchCommand(INSERT_UNORDERED_LIST_COMMAND)}>
        • 列表
      </button>
      <button style={btnStyle(false)}
        onClick={() => editor.dispatchCommand(INSERT_ORDERED_LIST_COMMAND)}>
        1. 列表
      </button>

      <span style={{ width: 1, height: 24, background: '#d9d9d9', margin: '0 6px', alignSelf: 'center' }} />

      {/* 撤销/重做 */}
      <button style={btnStyle(false)}
        onClick={() => editor.dispatchCommand(UNDO_COMMAND)}>
        ↩ 撤销
      </button>
      <button style={btnStyle(false)}
        onClick={() => editor.dispatchCommand(REDO_COMMAND)}>
        ↪ 重做
      </button>
    </div>
  );
}

// ============ HTML导出插件 ============

function HtmlExportPlugin({ onHtmlChange }) {
  const [editor] = useLexicalComposerContext();

  React.useEffect(() => {
    return editor.registerUpdateListener(({ editorState }) => {
      editorState.read(() => {
        const html = $generateHtmlFromNodes(editor);
        onHtmlChange?.(html);
      });
    });
  }, [editor, onHtmlChange]);

  return null;
}

// ============ 自动保存插件 ============

function AutoSavePlugin({ interval = 5000 }) {
  const [editor] = useLexicalComposerContext();

  React.useEffect(() => {
    let hasChanges = false;

    const unregister = editor.registerUpdateListener(() => {
      hasChanges = true;
    });

    const timer = setInterval(() => {
      if (hasChanges) {
        const editorState = editor.getEditorState();
        const json = JSON.stringify(editorState.toJSON());
        localStorage.setItem('lexical-draft', json);
        console.log('自动保存成功');
        hasChanges = false;
      }
    }, interval);

    return () => {
      unregister();
      clearInterval(timer);
    };
  }, [editor, interval]);

  return null;
}

// ============ 恢复草稿插件 ============

function RestoreDraftPlugin() {
  const [editor] = useLexicalComposerContext();

  React.useEffect(() => {
    const draft = localStorage.getItem('lexical-draft');
    if (draft) {
      try {
        const state = editor.parseEditorState(draft);
        editor.setEditorState(state);
        console.log('草稿已恢复');
      } catch (e) {
        console.warn('草稿恢复失败:', e);
      }
    }
  }, [editor]);

  return null;
}

// ============ 主组件 ============

export default function LexicalEditor() {
  const [htmlOutput, setHtmlOutput] = React.useState('');

  const onChange = useCallback((editorState) => {
    // editorState 是不可变的，可以安全序列化
    const json = editorState.toJSON();
    console.log('Editor state:', json);
  }, []);

  return (
    <div style={{ maxWidth: 800, margin: '40px auto' }}>
      <LexicalComposer initialConfig={editorConfig}>
        <div style={{
          border: '1px solid #d9d9d9',
          borderRadius: 8,
          overflow: 'hidden',
        }}>
          {/* 工具栏 */}
          <ToolbarPlugin />

          {/* 编辑区 */}
          <div style={{ padding: '16px 20px', minHeight: 300, position: 'relative' }}>
            <RichTextPlugin
              contentEditable={
                <ContentEditable
                  style={{
                    outline: 'none',
                    fontSize: 15,
                    lineHeight: 1.75,
                    minHeight: 250,
                  }}
                />
              }
              placeholder={
                <div style={{
                  position: 'absolute',
                  top: 16,
                  left: 20,
                  color: '#adb5bd',
                  pointerEvents: 'none',
                  fontSize: 15,
                }}>
                  开始写作...（支持 Markdown 快捷输入）
                </div>
              }
              ErrorBoundary={LexicalErrorBoundary}
            />
          </div>

          {/* 功能插件（不渲染UI，纯逻辑） */}
          <HistoryPlugin />
          <ListPlugin />
          <LinkPlugin />
          <MarkdownShortcutPlugin transformers={TRANSFORMERS} />
          <OnChangePlugin onChange={onChange} />
          <HtmlExportPlugin onHtmlChange={setHtmlOutput} />
          <AutoSavePlugin interval={5000} />
          <RestoreDraftPlugin />
        </div>
      </LexicalComposer>

      {/* HTML 输出预览 */}
      <div style={{
        marginTop: 24,
        padding: 16,
        border: '1px solid #e8e8e8',
        borderRadius: 8,
        background: '#fafafa',
      }}>
        <h3>HTML 输出：</h3>
        <pre style={{
          background: '#282c34',
          color: '#abb2bf',
          padding: 12,
          borderRadius: 4,
          overflow: 'auto',
          maxHeight: 200,
          fontSize: 13,
        }}>
          {htmlOutput}
        </pre>
      </div>
    </div>
  );
}

Lexical 对应的 CSS：

/* lexical-theme.css */
.editor-paragraph { margin-bottom: 8px; line-height: 1.75; }
.editor-h1 { font-size: 2em; font-weight: 700; margin: 16px 0 8px; }
.editor-h2 { font-size: 1.5em; font-weight: 700; margin: 12px 0 6px; }
.editor-h3 { font-size: 1.25em; font-weight: 600; margin: 10px 0 4px; }
.editor-bold { font-weight: 700; }
.editor-italic { font-style: italic; }
.editor-underline { text-decoration: underline; }
.editor-strikethrough { text-decoration: line-through; }
.editor-code-inline {
  background: #f0f0f0;
  color: #d63384;
  padding: 2px 6px;
  border-radius: 3px;
  font-family: monospace;
  font-size: 0.9em;
}
.editor-quote {
  border-left: 4px solid #1890ff;
  padding: 12px 16px;
  margin: 8px 0;
  color: #666;
  background: #f9f9f9;
}
.editor-code-block {
  background: #282c34;
  color: #abb2bf;
  padding: 16px;
  border-radius: 8px;
  font-family: 'Fira Code', monospace;
  font-size: 14px;
  overflow: auto;
}
.editor-ul { padding-left: 24px; list-style-type: disc; }
.editor-ol { padding-left: 24px; list-style-type: decimal; }
.editor-li { margin: 4px 0; }
.editor-link { color: #1890ff; text-decoration: underline; }

3.6 Quill —— 轻量级快速方案

适用场景： 评论框、简单编辑、快速集成

npm install quill@1.3.7
# Vue 封装
npm install vue-quill-editor

<template>
  <div class="quill-wrapper">
    <quill-editor
      ref="editor"
      v-model="content"
      :options="editorOptions"
      @change="onEditorChange"
      @focus="onEditorFocus"
      @blur="onEditorBlur"
    />
    <div class="char-count">{{ charCount }} / {{ maxLength }} 字</div>
  </div>
</template>

<script>
import 'quill/dist/quill.snow.css';
import { quillEditor } from 'vue-quill-editor';

// 自定义图片上传handler
function imageHandler() {
  const input = document.createElement('input');
  input.setAttribute('type', 'file');
  input.setAttribute('accept', 'image/*');
  input.click();

  input.onchange = async () => {
    const file = input.files[0];
    if (!file) return;

    // 文件大小校验
    if (file.size > 5 * 1024 * 1024) {
      alert('图片不能超过5MB');
      return;
    }

    const formData = new FormData();
    formData.append('file', file);

    try {
      const res = await fetch('/api/upload', {
        method: 'POST',
        body: formData,
      });
      const { url } = await res.json();

      // 获取光标位置，插入图片
      const quill = this.quill;
      const range = quill.getSelection(true);
      quill.insertEmbed(range.index, 'image', url);
      quill.setSelection(range.index + 1);
    } catch (err) {
      console.error('上传失败:', err);
    }
  };
}

export default {
  name: 'QuillEditorDemo',
  components: { quillEditor },

  props: {
    value: { type: String, default: '' },
    maxLength: { type: Number, default: 10000 },
  },

  data() {
    return {
        content: this.value,
        editorOptions: {
        theme: 'snow',
        placeholder: '请输入内容...',
        modules: {
          toolbar: {
            container: [
              [{ header: [1, 2, 3, 4, false] }],
              ['bold', 'italic', 'underline', 'strike'],
              [{ color: [] }, { background: [] }],
              [{ align: [] }],
              [{ list: 'ordered' }, { list: 'bullet' }],
              [{ indent: '-1' }, { indent: '+1' }],
              ['blockquote', 'code-block'],
              ['link', 'image', 'video'],
              ['clean'], // 清除格式
            ],
            // 自定义处理函数
            handlers: {
              image: imageHandler,
            },
          },

          // 剪贴板配置：控制粘贴行为
          clipboard: {
            matchVisual: false, // 不匹配视觉样式（减少脏HTML）
          },

          // 语法高亮（需要额外安装 highlight.js）
          // syntax: {
          //   highlight: (text) => hljs.highlightAuto(text).value,
          // },

          // 历史记录
          history: {
            delay: 1000,
            maxStack: 100,
            userOnly: true,
          },
        },

        // 支持的格式白名单（安全考虑）
        formats: [
          'header',
          'bold', 'italic', 'underline', 'strike',
          'color', 'background',
          'align',
          'list', 'indent',
          'blockquote', 'code-block',
          'link', 'image', 'video',
        ],
      },
    };
  },

  computed: {
    charCount() {
      // 获取纯文本长度
      if (!this.$refs.editor) return 0;
      const quill = this.$refs.editor.quill;
      if (!quill) return 0;
      return quill.getText().trim().length;
    },
  },

  watch: {
    value(newVal) {
      if (newVal !== this.content) {
        this.content = newVal;
      }
    },
    content(newVal) {
      this.$emit('input', newVal);
    },
  },

  methods: {
    onEditorChange({ quill, html, text }) {
      // 字数限制
      if (text.trim().length > this.maxLength) {
        quill.deleteText(this.maxLength, quill.getLength());
        return;
      }
      this.$emit('change', { html, text, delta: quill.getContents() });
    },

    onEditorFocus(quill) {
      this.$emit('focus', quill);
    },

    onEditorBlur(quill) {
      this.$emit('blur', quill);
    },

    // ====== 外部 API ======
    getQuill() {
      return this.$refs.editor?.quill;
    },
    getHTML() {
      return this.content;
    },
    getText() {
      return this.getQuill()?.getText()?.trim() || '';
    },
    getDelta() {
      return this.getQuill()?.getContents();
    },
    setHTML(html) {
      this.content = html;
    },
    clear() {
      this.content = '';
    },
    focus() {
      this.getQuill()?.focus();
    },
    disable() {
      this.getQuill()?.enable(false);
    },
    enable() {
      this.getQuill()?.enable(true);
    },
    // 插入文本到光标位置
    insertText(text) {
      const quill = this.getQuill();
      const range = quill.getSelection(true);
      quill.insertText(range.index, text);
    },
    // 插入嵌入内容
    insertEmbed(type, value) {
      const quill = this.getQuill();
      const range = quill.getSelection(true);
      quill.insertEmbed(range.index, type, value);
      quill.setSelection(range.index + 1);
    },
  },

  mounted() {
    // 可在此注册自定义 Blot（Quill 的扩展机制）
    this.registerCustomBlots();
  },

  methods: {
    // ...上面的方法

    registerCustomBlots() {
      const Quill = require('quill');
      const Inline = Quill.import('blots/inline');

      // 自定义 @提及 Blot
      class MentionBlot extends Inline {
        static create(data) {
          const node = super.create();
          node.setAttribute('data-mention-id', data.id);
          node.setAttribute('data-mention-name', data.name);
          node.textContent = `@${data.name}`;
          node.style.cssText = 'color:#1890ff;background:#e6f7ff;padding:0 4px;border-radius:2px;';
          return node;
        }
        static value(node) {
          return {
            id: node.getAttribute('data-mention-id'),
            name: node.getAttribute('data-mention-name'),
          };
        }
        static formats(node) {
          return {
            id: node.getAttribute('data-mention-id'),
            name: node.getAttribute('data-mention-name'),
          };
        }
      }
      MentionBlot.blotName = 'mention';
      MentionBlot.tagName = 'span';
      MentionBlot.className = 'mention-tag';

      Quill.register(MentionBlot);
    },
  },
};
</script>

<style scoped>
.quill-wrapper {
  position: relative;
}
.quill-wrapper >>> .ql-container {
  min-height: 300px;
  font-size: 15px;
  line-height: 1.75;
}
.quill-wrapper >>> .ql-editor {
  min-height: 300px;
  padding: 16px 20px;
}
.quill-wrapper >>> .ql-toolbar {
  border-top-left-radius: 8px;
  border-top-right-radius: 8px;
}
.quill-wrapper >>> .ql-container {
  border-bottom-left-radius: 8px;
  border-bottom-right-radius: 8px;
}
.char-count {
  position: absolute;
  bottom: 8px;
  right: 12px;
  font-size: 12px;
  color: #999;
}
</style>

四、协同编辑实现（Tiptap + Yjs）

这是最常被问到的高级功能，以下是完整的实现方案：

4.1 架构图

┌──────────────────────────────────────────────────────────┐
│                   协同编辑架构                             │
│                                                          │
│  ┌─────────┐    WebSocket    ┌──────────────┐            │
│  │ 客户端A  │ ◄────────────► │              │            │
│  │ Tiptap   │                │   Yjs Server │            │
│  │ + Y.js   │                │  (y-websocket│            │
│  └─────────┘                │   provider)  │            │
│                              │              │            │
│  ┌─────────┐    WebSocket    │              │            │
│  │ 客户端B  │ ◄────────────► │              │            │
│  │ Tiptap   │                └──────┬───────┘            │
│  │ + Y.js   │                       │                    │
│  └─────────┘                   持久化存储                 │
│                              ┌──────┴───────┐            │
│  ┌─────────┐                 │   LevelDB /  │            │
│  │ 客户端C  │ ...            │   PostgreSQL │            │
│  └─────────┘                 └──────────────┘            │
│                                                          │
│  Yjs 使用 CRDT 算法，无需中心化冲突解决                     │
│  每个客户端维护本地文档副本，增量同步                        │
└──────────────────────────────────────────────────────────┘

4.2 服务端

npm install y-websocket y-leveldb

// server/collab-server.js

const http = require('http');
const WebSocket = require('ws');
const { setupWSConnection } = require('y-websocket/bin/utils');
const { LeveldbPersistence } = require('y-leveldb');

// 持久化存储
const persistence = new LeveldbPersistence('./yjs-docs');

const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Yjs WebSocket Server Running');
});

const wss = new WebSocket.Server({ server });

wss.on('connection', (ws, req) => {
  // 从 URL 中获取文档 ID
  const docName = req.url.slice(1).split('?')[0] || 'default';

  console.log(`[Collab] Client connected to doc: ${docName}`);
  console.log(`[Collab] Active connections: ${wss.clients.size}`);

  // 建立 Yjs WebSocket 连接
  setupWSConnection(ws, req, {
    docName,
    persistence,
    // gc: true, // 垃圾回收
  });

  ws.on('close', () => {
    console.log(`[Collab] Client disconnected from doc: ${docName}`);
  });
});

const PORT = 1234;
server.listen(PORT, () => {
  console.log(`[Collab] WebSocket server running on ws://localhost:${PORT}`);
});

4.3 客户端（Tiptap + Yjs）

# 安装协同依赖
npm install yjs y-websocket @tiptap/extension-collaboration \
  @tiptap/extension-collaboration-cursor

<template>
  <div class="collab-editor">
    <!-- 在线用户列表 -->
    <div class="online-users">
      <span class="label">在线：</span>
      <span
        v-for="user in onlineUsers"
        :key="user.clientId"
        class="user-badge"
        :style="{ background: user.color }"
      >
        {{ user.name }}
      </span>
      <span v-if="!connected" class="status-disconnected">⚠ 连接断开，尝试重连中...</span>
    </div>

    <!-- 工具栏（复用上面Tiptap的工具栏，此处省略） -->
    <div v-if="editor" class="toolbar">
      <button
        @click="editor.chain().focus().toggleBold().run()"
        :class="{ active: editor.isActive('bold') }"
      >B</button>
      <button
        @click="editor.chain().focus().toggleItalic().run()"
        :class="{ active: editor.isActive('italic') }"
      >I</button>
      <!-- ...其他按钮 -->
    </div>

    <!-- 编辑区 -->
    <editor-content :editor="editor" class="editor-content" />

    <!-- 连接状态 -->
    <div class="status-bar">
      <span :class="connected ? 'status-online' : 'status-offline'">
        {{ connected ? '● 已连接' : '○ 离线' }}
      </span>
      <span>{{ onlineUsers.length }} 人在线</span>
    </div>
  </div>
</template>

<script>
import { Editor, EditorContent } from '@tiptap/vue-2';
import StarterKit from '@tiptap/starter-kit';
import Collaboration from '@tiptap/extension-collaboration';
import CollaborationCursor from '@tiptap/extension-collaboration-cursor';
import * as Y from 'yjs';
import { WebsocketProvider } from 'y-websocket';

// 随机颜色
const COLORS = [
  '#f44336', '#e91e63', '#9c27b0', '#673ab7',
  '#3f51b5', '#2196f3', '#03a9f4', '#00bcd4',
  '#009688', '#4caf50', '#8bc34a', '#ff9800',
];
function getRandomColor() {
  return COLORS[Math.floor(Math.random() * COLORS.length)];
}

// 获取当前用户信息（实际从登录状态获取）
function getCurrentUser() {
  const stored = localStorage.getItem('collab-user');
  if (stored) return JSON.parse(stored);

  const user = {
    name: '用户' + Math.floor(Math.random() * 1000),
    color: getRandomColor(),
  };
  localStorage.setItem('collab-user', JSON.stringify(user));
  return user;
}

export default {
  name: 'CollabEditor',
  components: { EditorContent },

  props: {
    // 文档ID，不同ID对应不同文档
    docId: {
      type: String,
      required: true,
    },
    wsUrl: {
      type: String,
      default: 'ws://localhost:1234',
    },
  },

  data() {
    return {
      editor: null,
      provider: null,
      ydoc: null,
      connected: false,
      onlineUsers: [],
      currentUser: getCurrentUser(),
    };
  },

  mounted() {
    this.initCollabEditor();
  },

  methods: {
    initCollabEditor() {
      // 1. 创建 Yjs 文档
      this.ydoc = new Y.Doc();

      // 2. 创建 WebSocket Provider（连接服务端）
      this.provider = new WebsocketProvider(
        this.wsUrl,
        this.docId, // 文档标识符
        this.ydoc,
        {
          connect: true,
          // 自动重连配置
          resyncInterval: 3000,
          maxBackoffTime: 10000,
          // WebSocket 参数
          params: {
            // token: 'xxx', // 可传认证token
          },
        }
      );

      // 3. 监听连接状态
      this.provider.on('status', ({ status }) => {
        this.connected = status === 'connected';
        console.log(`[Collab] 连接状态: ${status}`);
      });

      // 4. 设置当前用户的 awareness 信息（光标、用户名等）
      this.provider.awareness.setLocalStateField('user', {
        name: this.currentUser.name,
        color: this.currentUser.color,
      });

      // 5. 监听在线用户变化
      this.provider.awareness.on('change', () => {
        const states = this.provider.awareness.getStates();
        this.onlineUsers = [];
        states.forEach((state, clientId) => {
          if (state.user) {
            this.onlineUsers.push({
              clientId,
              ...state.user,
            });
          }
        });
      });

      // 6. 创建编辑器
      this.editor = new Editor({
        extensions: [
          StarterKit.configure({
            // 使用 Collaboration 的历史记录，禁用默认的
            history: false,
          }),

          // 协同编辑核心扩展
          Collaboration.configure({
            document: this.ydoc,
            // 指定 Yjs 中的 XML Fragment 字段名
            field: 'content',
          }),

          // 协同光标
          CollaborationCursor.configure({
            provider: this.provider,
            user: this.currentUser,
            // 自定义光标渲染
            render: (user) => {
              const cursor = document.createElement('span');
              cursor.classList.add('collab-cursor');
              cursor.style.borderColor = user.color;

              const label = document.createElement('span');
              label.classList.add('collab-cursor-label');
              label.style.background = user.color;
              label.textContent = user.name;
              cursor.appendChild(label);

              return cursor;
            },
          }),
        ],

        // 不需要设置初始 content，Yjs 会从服务端同步
      });
    },

    // 断开连接
    disconnect() {
      this.provider?.disconnect();
    },

    // 重新连接
    reconnect() {
      this.provider?.connect();
    },

    // 获取文档快照（用于导出）
    getSnapshot() {
      return {
        html: this.editor.getHTML(),
        json: this.editor.getJSON(),
        // Yjs 二进制快照（可用于恢复）
        yjsState: Y.encodeStateAsUpdate(this.ydoc),
      };
    },

    // 从快照恢复
    restoreFromSnapshot(yjsState) {
      Y.applyUpdate(this.ydoc, new Uint8Array(yjsState));
    },
  },

  watch: {
    docId(newId, oldId) {
      if (newId !== oldId) {
        // 文档切换时，销毁旧连接，建立新连接
        this.destroy();
        this.initCollabEditor();
      }
    },
  },

  beforeDestroy() {
    this.destroy();
  },

  methods: {
    // ... 上面的methods

    destroy() {
      this.editor?.destroy();
      this.provider?.disconnect();
      this.provider?.destroy();
      this.ydoc?.destroy();
    },
  },
};
</script>

<style>
.collab-editor {
  border: 1px solid #d9d9d9;
  border-radius: 8px;
  overflow: hidden;
}

/* 在线用户列表 */
.online-users {
  display: flex;
  align-items: center;
  gap: 8px;
  padding: 8px 12px;
  background: #f0f0f0;
  border-bottom: 1px solid #e8e8e8;
  font-size: 13px;
}
.online-users .label {
  color: #666;
}
.user-badge {
  padding: 2px 8px;
  border-radius: 12px;
  color: white;
  font-size: 12px;
}
.status-disconnected {
  color: #ff4d4f;
  margin-left: auto;
}

/* 协同光标样式 */
.collab-cursor {
  position: relative;
  border-left: 2px solid;
  margin-left: -1px;
  margin-right: -1px;
  pointer-events: none;
  word-break: normal;
}
.collab-cursor-label {
  position: absolute;
  top: -1.4em;
  left: -1px;
  padding: 1px 6px;
  border-radius: 4px 4px 4px 0;
  color: white;
  font-size: 11px;
  font-weight: 500;
  white-space: nowrap;
  user-select: none;
  pointer-events: none;
  line-height: 1.4;
}

/* 状态栏 */
.status-bar {
  display: flex;
  gap: 16px;
  padding: 6px 16px;
  border-top: 1px solid #e8e8e8;
  background: #fafafa;
  font-size: 12px;
}
.status-online { color: #52c41a; }
.status-offline { color: #ff4d4f; }
</style>

深度拆解 fetch-event-source库实现原理

掘金前端

作者发现一只大呆瓜

2026年3月17日 17:38

前言

在 AI 大模型火热的今天，流式输出（Streaming）已成为标配。虽然浏览器原生提供了 EventSource (SSE)，但在复杂的业务实战中，它却显得力不从心。本文将带你深度剖析 fetch-event-source 的底层实现，看看它是如何突破原生限制，优雅实现流式交互的。

一、为什么原生 EventSource 走到了尽头？

原生 EventSource 在 AI 聊天场景中有两个“死穴”：

方法受限：只能发送 GET 请求。AI 聊天往往需要携带庞大的上下文（Context），URL 长度限制是无法逾越的障碍。
鉴权困境：无法自定义 Header。在需要通过 Authorization 传递 Token 的现代 Web 应用中，这非常致命。

fetch-event-source 的出现，本质上是给 fetch 套上了一层 SSE 的协议外壳，完美继承了 fetch 的灵活性。

二、核心原理：基于 ReadableStream 的流式解析

fetch-event-source 的核心魔法在于利用了 fetch 返回值中的 Response.body。它是一个 ReadableStream（可读流），允许我们在数据还没全部到达时，就开始处理已经“流”进来的字节块。

1. 协议头强制对齐

要模拟 SSE，请求头必须严格遵守规范：

Accept: text/event-stream：告知后端我们需要流式响应。
Cache-Control: no-cache：禁用缓存，确保实时性。
Connection: keep-alive：保持长连接。

2. 状态机解析逻辑

由于 SSE 格式具有高度可预测性（以 \n 分隔行，以 \n\n 分隔消息块），我们可以通过一个简单的状态机进行逐行扫描：

data: 开头 -> 暂存数据片段。
event: 开头 -> 记录事件类型。
retry: 开头 -> 更新客户端的重连等待时间。
空行 (\n\n) -> 表示一条消息解析完成，触发 onmessage 回调。

三、手写一个简易版

理解原理最好的方式就是复刻它。以下是基于 fetch 和 TextDecoder 的核心实现逻辑：

async function fetchEventSource(url, options) {
  const { signal, onopen, onmessage, onerror, retryDelay = 1000 } = options;
  let retryCount = 0;

  // 1. 循环处理（失败重试）
  while (!signal.aborted) {
    try {
      const response = await fetch(url, {
        method: 'POST', // 突破 GET 限制，支持 POST 发送上下文
        headers: {
          'Accept': 'text/event-stream',
          'Cache-Control': 'no-cache',
          'Content-Type': 'application/json',
          ...options.headers,
        },
        body: JSON.stringify(options.body),
        signal,
      });

      // 2. 响应合法性校验
      if (!response.ok) throw new Error(`HTTP error! status: ${response.status}`);
      if (!response.headers.get('Content-Type')?.includes('text/event-stream')) {
        throw new Error('Invalid Content-Type, expected text/event-stream');
      }

      onopen?.({ response });

      // 3. 读取流式响应体 (核心)
      const reader = response.body.getReader();
      const decoder = new TextDecoder('utf-8');
      let buffer = ''; 

      while (true) {
        const { done, value } = await reader.read();
        if (done) break;

        // 解码二进制数据并追加到缓冲区
        buffer += decoder.decode(value, { stream: true });
        
        // 4. 按 SSE 规范拆分消息块 (\n\n)
        let parts = buffer.split('\n\n');
        buffer = parts.pop(); // 最后一个可能是残缺的，留到下一轮处理

        for (const part of parts) {
          // 这里解析 data: event: 等字段
          const parsed = parseSSEPart(part); 
          onmessage?.(parsed);
        }
      }

      await reader.releaseLock();
      if (signal.aborted) break;

      throw new Error('Connection closed by server');
    } catch (error) {
      // 5. 错误处理与指数退避重连
      const retry = onerror?.(error) ?? true;
      if (!retry || signal.aborted) break;

      const delay = retryDelay * Math.pow(2, retryCount);
      await new Promise(resolve => setTimeout(resolve, delay));
      retryCount++;
    }
  }
}

四、总结

fetch-event-source 并不是魔法，它只是站在了 fetch 和 ReadableStream 的肩膀上，通过手动实现 SSE 协议解析，解决了原生 API 的痛点。在 AI 对话应用中，它是实现实时、鉴权、高扩展性流式输出的最佳实践。

ES2025 JavaScript 新特性预览

掘金前端

作者敲代码的约德尔人

2026年3月17日 17:29

ES2025 JavaScript 新特性预览

从 Temporal 日期时间 API 到装饰器语法，抢先了解 JavaScript 语言的最新演进方向

前言

JavaScript 语言一直在不断演进，每年都有新特性加入 ECMAScript 标准。

ES2025 即将带来哪些令人期待的新特性？

Temporal 日期时间 API 终于要来了
装饰器语法历经多年修订即将定稿
显式资源管理让代码更简洁
模块延迟加载优化大型应用性能

下面我们来详细了解这些新特性，掌握 JavaScript 语言的最新发展方向。

一、Temporal 日期时间 API

现有 Date API 的问题

JavaScript 的 Date API 一直被开发者诟病：

// 不推荐：Date 是可变对象
const date = new Date();
date.setMonth(date.getMonth() + 1); // 修改了原对象

// 不推荐：月份从 0 开始，容易混淆
const date = new Date(2024, 1, 1); // 2 月 1 日，不是 1 月 1 日

// 不推荐：时区处理复杂
const date = new Date();
date.getTimezoneOffset(); // 返回分钟数，需要手动计算

// 不推荐：精度低
const now = Date.now(); // 毫秒级精度

Temporal 的核心优势

1. 不可变对象

const date = Temporal.Now.plainDateISO();
const nextMonth = date.add({ months: 1 }); // 返回新对象，不修改原对象

2. 直观的 API

// 创建日期
const date = Temporal.PlainDate.from('2024-02-01');
console.log(date.month); // 2（不是 1）
console.log(date.day); // 1

// 日期计算
const tomorrow = date.add({ days: 1 });
const nextYear = date.add({ years: 1 });

3. 时区友好

// 获取当前时区的日期时间
const now = Temporal.Now.plainDateTimeISO();

// 指定时区
const tokyoTime = Temporal.Now.plainDateTimeISO('Asia/Tokyo');

// 时区转换
const zoned = date.toZonedDateTime({ timeZone: 'America/New_York' });

4. 高精度

const instant = Temporal.Now.instant();
console.log(instant.epochNanoseconds); // 纳秒级精度

实战示例

// 计算两个日期之间的差异
const start = Temporal.PlainDate.from('2024-01-01');
const end = Temporal.PlainDate.from('2024-12-31');

const diff = end.since(start, { largestUnit: 'months' });
console.log(diff.months); // 11

// 日期比较
if (end.compareTo(start) > 0) {
  console.log('end 在 start 之后');
}

// 日历计算
const chineseNewYear = Temporal.PlainDate.from('2024-02-10');
const duration = chineseNewYear.since(start);
console.log(duration.days); // 40

二、装饰器语法（Decorators）

装饰器的作用

装饰器为类和类方法提供元编程能力，可以在不修改原有代码的情况下添加功能。

最终语法（2025 版）

// 类装饰器
function logged(target, context) {
  return function(...args) {
    console.log(`Calling ${context.name}`);
    return target(...args);
  };
}

class MyClass {
  @logged
  myMethod() {
    console.log('执行中');
  }
}

// 使用
const obj = new MyClass();
obj.myMethod();
// 输出：
// Calling myMethod
// 执行中

常见装饰器示例

1. 只读属性

function readonly(target, context) {
  return {
    get() {
      return target.get.call(this);
    },
    set(value) {
      throw new Error('Cannot assign to read-only property');
    }
  };
}

class Person {
  @readonly
  name = 'John';
}

const p = new Person();
console.log(p.name); // John
p.name = 'Jane'; // 抛出错误

2. 缓存方法结果

function cached(target, context) {
  const cache = new WeakMap();
  
  return function(...args) {
    const key = JSON.stringify(args);
    if (cache.has(this) && cache.get(this).has(key)) {
      return cache.get(this).get(key);
    }
    
    const result = target.call(this, ...args);
    
    if (!cache.has(this)) {
      cache.set(this, new Map());
    }
    cache.get(this).set(key, result);
    
    return result;
  };
}

class Calculator {
  @cached
  expensiveCalculation(x, y) {
    console.log('计算中...');
    return x + y;
  }
}

const calc = new Calculator();
calc.expensiveCalculation(1, 2); // 计算中...
calc.expensiveCalculation(1, 2); // 直接从缓存返回

3. 自动绑定 this

function autobind(target, context) {
  return function(...args) {
    return target.call(this, ...args);
  };
}

class Button {
  constructor() {
    this.clicked = false;
  }
  
  @autobind
  handleClick() {
    this.clicked = true;
    console.log('Button clicked');
  }
}

const button = new Button();
const handler = button.handleClick;
handler(); // this 正确绑定

三、显式资源管理

问题背景

JavaScript 中经常需要手动管理资源：

// 需要手动关闭文件
const file = openFile('test.txt');
try {
  const content = file.read();
  console.log(content);
} finally {
  file.close(); // 容易忘记
}

using 关键字

// 自动管理资源
{
  using file = openFile('test.txt');
  const content = file.read();
  console.log(content);
} // 自动调用 file.close()

// 多个资源
{
  using file1 = openFile('a.txt');
  using file2 = openFile('b.txt');
  // 按相反顺序自动关闭
}

实现原理

// 可处置对象
class Resource {
  [Symbol.dispose]() {
    console.log('资源已释放');
  }
}

// 使用
{
  using resource = new Resource();
  // 使用资源
} // 自动调用 [Symbol.dispose]()

异步资源管理

// await using 用于异步资源
{
  await using connection = await openDatabase();
  const data = await connection.query('SELECT * FROM users');
  console.log(data);
} // 自动调用 await connection.close()

四、模块延迟加载

问题背景

大型应用中，模块加载可能影响首屏性能：

// 所有模块立即加载
import { heavyModule } from './heavy.js';
import { anotherModule } from './another.js';

// 即使暂时用不到，也会阻塞加载

defer 关键字

// 延迟加载
import defer { heavyModule } from './heavy.js';

// 模块不会立即加载，直到实际使用
heavyModule.doSomething(); // 此时才加载

条件加载

// 根据条件加载
if (featureEnabled) {
  import defer { featureModule } from './feature.js';
  featureModule.init();
}

五、其他新特性

1. Source Phase Imports

允许在编译时导入资源：

// 导入源码而非执行结果
import source mySource from './module.js';

console.log(mySource); // 模块的源代码字符串

应用场景：

类型定义导入
代码转换工具
静态分析

2. Atomics.pause

优化自旋锁性能：

// 等待共享内存状态改变
while (Atomics.load(sharedArray, 0) === 0) {
  Atomics.pause(); // 让出 CPU，降低功耗
}

3. Array Buffer 转移

// 转移 ArrayBuffer 的所有权
const buffer1 = new ArrayBuffer(1024);
const buffer2 = buffer1.transfer();

console.log(buffer1.byteLength); // 0
console.log(buffer2.byteLength); // 1024

优势：避免复制大缓冲区，提升性能。

六、特性成熟度

特性	Stage	预计发布
Temporal	Stage 3	2025 年
Decorators	Stage 3	2025 年
Explicit Resource Management	Stage 3	2025 年
Deferring Module Evaluation	Stage 2	2026 年
Source Phase Imports	Stage 2	2026 年
Atomics.pause	Stage 2	2025 年

Stage 说明：

Stage 2：提案阶段，可能变化
Stage 3：候选阶段，基本稳定
Stage 4：完成阶段，将加入标准

七、如何使用新特性

1. Babel 转译

Babel 是最常用的 JavaScript 转译工具，可以将新特性转译为兼容旧环境的代码。

安装方式：

npm install @babel/core @babel/cli

配置 .babelrc：

{
  "plugins": [
    "@babel/plugin-proposal-decorators",
    "@babel/plugin-proposal-explicit-resource-management"
  ]
}

适用场景：需要在生产环境使用 ES2025 新特性，且目标浏览器不支持时。

2. TypeScript 支持

TypeScript 对部分 ES2025 特性提供了实验性支持。

安装方式：

npm install -D typescript

配置 tsconfig.json：

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "target": "ESNext"
  }
}

适用场景：使用 TypeScript 开发，需要类型检查和新特性支持。

3. 浏览器支持

查看兼容性：caniuse.com/

目前大多数新特性需要转译才能在生产环境使用。建议在实验性项目中尝试，生产环境谨慎使用。

总结

ES2025 带来的新特性将显著提升 JavaScript 的开发体验：

Temporal - 解决 Date API 的所有痛点
装饰器 - 提供强大的元编程能力
显式资源管理 - 自动清理，避免泄漏
模块延迟加载 - 优化大型应用性能

建议关注 TC39 提案进展，在实验性项目中尝试新特性，生产环境使用 Babel 或 TypeScript 转译。

JavaScript 语言仍在快速发展，保持学习才能跟上时代。

参考资料

TC39 Proposals: github.com/tc39/propos…
Temporal Proposal: tc39.es/proposal-te…
Decorators Proposal: github.com/tc39/propos…
Explicit Resource Management: github.com/tc39/propos…
MDN - JavaScript 新特性：developer.mozilla.org/zh-CN/docs/…

觉得文章对你有帮助？欢迎点赞收藏，分享给更多需要的朋友！

SSE 流式传输：中断超时处理

掘金前端

作者发现一只大呆瓜

2026年3月17日 17:23

前言

在开发 AI 聊天应用时，fetch-event-source 几乎是前端标配。但你是否思考过：为什么原生的 EventSource 不行？它是如何解析二进制流的？当网络波动导致连接“假死”时，如何实现无感重连和数据去重？本文将带你拆解这些核心细节。

一、为什么原生 EventSource 在 AI 场景“退环境”了？

原生 EventSource 虽好，但在复杂的 AI 业务场景中有两个“致命伤”：

仅支持 GET 请求：AI 对话通常需要发送长篇累牍的上下文（Context），URL 长度限制会导致请求失败。
无法自定义 Header：无法在请求头中携带 Authorization 令牌，给鉴权带来了麻烦。

fetch-event-source 的原理：它是基于原生 fetch 的 ReadableStream（可读流） 实现的。它通过手动解析 HTTP 响应体中的二进制数据，模拟了 SSE 的行为，同时继承了 fetch 支持各种 Method 和 Header 的灵活性。

二、核心实战：如何处理 SSE 异常中断与超时？

在长连接中，最怕“连接还在，但数据没了”的假死状态。我们需要对库进行二次封装，引入超时检测与指数退避重连。

1. 超时检测机制

设置一个心跳定时器。如果在规定时间内（如 15s）没有收到任何 onmessage 信号，说明连接可能已失效。

动作：主动调用 abort() 中断当前请求，并触发重连。
重置：每当有新数据到达或连接开启时，重置该定时器。

2. 指数退避自动重连

为了减轻服务器压力，重连间隔不应是固定的。

策略：从 2s 开始，每次失败翻倍（2s → 4s → 8s...），上限 30s。
终止：设置最大重连次数（如 10 次），失败后提示用户“服务器繁忙，请手动重试”。

3. 断点续传与去重

重连后，后端可能会重新推送历史数据。

前端方案：维护一个 lastMsgId。请求时带上这个标识，让后端从断点处开始推送；或者前端根据 id 对收到的消息进行 Map 去重。

三、中断超时处理实现：基于fetchEventSource 简易实现

import { fetchEventSource } from '@microsoft/fetch-event-source'
import { ElMessage, ElMessageBox } from 'element-plus'

// 全局状态管理（避免多请求冲突）
let controller = new AbortController()
let timeoutTimer = null // 超时定时器
let reconnectCount = 0 // 重连次数
let reconnectInterval = 2000 // 初始重连间隔（2s）
const MAX_RECONNECT_COUNT = 10 // 最大重连次数
const MAX_RECONNECT_INTERVAL = 30000 // 最大重连间隔（30s）
let lastMessageId = '' // 记录最后一条消息ID（断点续传用）

/**
 * 重置超时定时器（收到消息/建立连接时调用）
 * @param {number} timeout 超时时间（默认30s）
 */
const resetTimeoutTimer = (timeout = 30000) => {
  // 清除原有定时器
  if (timeoutTimer) clearTimeout(timeoutTimer)
  // 新建超时定时器：超时未收到消息则主动中断
  timeoutTimer = setTimeout(() => {
    ElMessage.warning('连接超时，正在尝试重连...')
    controller.abort() // 主动中断请求
    reconnectStream() // 触发重连
  }, timeout)
}

/**
 * 重连流式请求（指数退避策略）
 * @param {string} url 接口地址
 * @param {Object} headers 请求头
 * @param {Object} data 请求参数
 * @param {Function} handleMessage 消息处理回调
 */
const reconnectStream = async (url, headers, data, handleMessage) => {
  // 超过最大重连次数，停止自动重连
  if (reconnectCount >= MAX_RECONNECT_COUNT) {
    ElMessageBox.alert('服务器繁忙，请稍后手动重试', '重连失败', {
      confirmButtonText: '确定'
    })
    // 重置重连状态
    reconnectCount = 0
    reconnectInterval = 2000
    return
  }

  // 指数退避：间隔翻倍，不超过30s
  const currentInterval = Math.min(reconnectInterval, MAX_RECONNECT_INTERVAL)
  ElMessage.info(`第${reconnectCount + 1}次重连，间隔${currentInterval / 1000}s...`)

  // 延迟重连
  await new Promise((resolve) => setTimeout(resolve, currentInterval))

  // 更新重连状态
  reconnectCount++
  reconnectInterval *= 2

  // 重新发起请求（携带最后一条消息ID，实现断点续传）
  requestStream(
    url,
    headers,
    {
      ...data,
      lastMessageId: lastMessageId // 传给后端，让后端从断点续传
    },
    handleMessage
  )
}

/**
 * 流式请求核心方法（带超时、重连、断点续传）
 * @param {string} url 接口地址
 * @param {Object} headers 请求头
 * @param {Object} data 请求参数
 * @param {Function} handleMessage 消息处理回调（接收流式数据）
 */
export const requestStream = (url, headers, data, handleMessage) => {
  // 中断原有请求
  if (controller) controller.abort()
  controller = new AbortController()

  // 初始化超时定时器（30s超时检测）
  resetTimeoutTimer()

  fetchEventSource(url, {
    method: 'POST',
    signal: controller.signal,
    headers: {
      ...headers,
      Accept: 'text/event-stream', // SSE必需头
      'Cache-Control': 'no-cache'
    },
    body: JSON.stringify(data),
    openWhenHidden: true, // 页面隐藏时继续请求
    async onopen(response) {
      console.log('建立连接的回调')
      // 连接建立：重置超时定时器+重连状态
      resetTimeoutTimer()
      reconnectCount = 0
      reconnectInterval = 2000

      // 校验响应合法性
      if (!response.ok) {
        throw new Error(`连接失败，状态码：${response.status}`)
      }
    },
    onmessage(msg) {
      // 收到消息：重置超时定时器
      resetTimeoutTimer()

      // 记录最后一条消息ID（断点续传核心）
      if (msg.id) lastMessageId = msg.id
      // 处理消息（去重逻辑：避免重连后数据重复）
      handleMessage(msg)
    },
    onclose() {
      console.log('连接正常关闭')
      // 清除定时器+中断请求
      if (timeoutTimer) clearTimeout(timeoutTimer)
      controller.abort()
      // 重置状态
      reconnectCount = 0
      reconnectInterval = 2000
      lastMessageId = ''
    },
    onerror(err) {
      // 清除超时定时器
      if (timeoutTimer) clearTimeout(timeoutTimer)

      // 手动中断不触发重连（比如用户点击停止）
      if (controller.signal.aborted) {
        console.log('用户手动中断请求')
        return
      }

      // 异常重连
      ElMessage.error(`连接异常：${err.message || '网络错误'}`)
      reconnectStream(url, headers, data, handleMessage)

      // 必须抛出错误才会停止当前请求循环
      throw err
    }
  })
}

/**
 * 停止流式请求（手动中断）
 */
export const stopRequest = () => {
  // 清除超时定时器
  if (timeoutTimer) {
    clearTimeout(timeoutTimer)
    timeoutTimer = null
  }
  // 中断请求
  if (controller) {
    controller.abort()
    controller = new AbortController()
  }
  // 重置重连状态
  reconnectCount = 0
  reconnectInterval = 2000
  lastMessageId = ''
  ElMessage.info('已停止数据请求')
}

四、注意：关于 Nginx 与浏览器限制

Nginx 缓存屏蔽：一定要记得设置 proxy_buffering off;，否则 Nginx 会等缓冲区满了才一次性吐给前端，导致流式效果失效。
浏览器连接数限制：如果是 HTTP/1.1，浏览器对同一个域名的长连接通常限制在 6 个。如果打开多个 AI 对话页，可能会导致后续连接卡死。建议升级 HTTP/2，它可以多路复用，避开此限制。
手动停止 vs 自动重连：当用户点击“停止生成”时，必须标记一个 manualStop 状态位，否则 onerror 可能会误以为是网络异常而不断尝试重连。

五、💡 扩展：异步并发池 (Async Pool)

它不直接用于单个 SSE 连接，但在批量 AI 任务处理（例如一次性给 100 张图片生成描述）时非常有用。它可以限制同时进行的 HTTP 请求数量，防止瞬间撑爆浏览器带宽或后端并发限制。

1. 归属识别：唯一 ID + 专属缓存

每个请求分配requestId（如stream-request-0）；
streamDataCache以requestId为 key，每个请求的片段只往自己的缓存里加；
即使多个请求的onmessage同时触发，也不会串数据（比如stream-request-0的片段绝不会跑到stream-request-1的缓存里）。

2. 有序拼接：数组按顺序存储片段

每个请求的缓存里用fragments数组存储片段；
onmessage每次触发时，cache.fragments.push(msg.data)保证片段按返回顺序存储；
收到结束标识[DONE]时，用join('')拼接数组，得到完整结果。

3. 并发控制：不等待 Promise 完成，只控制启动数

runningRequestCount记录正在运行的请求数；
runTasks里用while (runningRequestCount >= limit)等待，直到有请求结束、并发数下降；
每个请求结束后（onclose/onerror），runningRequestCount--，并自动执行下一个任务；
这种方式既限制了并发数，又不阻塞流式请求的 “持续返回片段”。

/**
 * 异步任务池（适配流式请求的并发控制）
 * @param {Array<Object>} requestList 批量请求列表（含url/headers/data）
 * @param {number} limit 最大并发数
 * @param {Function} onComplete 单个请求完成回调（参数：requestId, fullResult）
 */
export const batchStreamRequest = async (requestList, limit = 3, onComplete) => {
  // 为每个请求分配唯一ID
  const requestListWithId = requestList.map((item, index) => ({
    ...item,
    requestId: `stream-request-${index}`
  }))

  // 任务执行队列：递归执行，控制并发数
  const runTasks = async (taskIndex = 0) => {
    // 所有任务处理完毕
    if (taskIndex >= requestListWithId.length) return

    const currentTask = requestListWithId[taskIndex]
    const { requestId, url, headers, data } = currentTask

    // 等待：直到并发数低于限制
    while (runningRequestCount >= limit) {
      await new Promise((resolve) => setTimeout(resolve, 100)) // 每100ms检查一次
    }

    // 启动当前流式请求
    runningRequestCount++
    console.log(`启动请求${requestId}，当前并发数：${runningRequestCount}`)

    // 执行单个流式请求（不等待完成，只标记启动）
    singleStreamRequest(requestId, url, headers, data, onComplete)
      .catch((err) => console.error(`请求${requestId}失败：`, err))
      .finally(() => {
        // 当前请求结束后，自动执行下一个任务
        runTasks(taskIndex + 1)
      })

    // 立即执行下一个任务（检查并发数）
    runTasks(taskIndex + 1)
  }

  // 启动任务队列
  await runTasks(0)
}

/**
 * 停止单个/所有流式请求
 * @param {string} [requestId] 可选：指定停止的请求ID，不传则停止所有
 */
export const stopStreamRequest = (requestId) => {
  if (requestId) {
    // 停止指定请求
    const controller = requestControllers[requestId]
    if (controller) {
      controller.abort()
      delete requestControllers[requestId]
      // 标记缓存为完成
      if (streamDataCache[requestId]) {
        streamDataCache[requestId].isCompleted = true
      }
      runningRequestCount--
    }
  } else {
    // 停止所有请求
    Object.keys(requestControllers).forEach((id) => {
      requestControllers[id].abort()
      delete requestControllers[id]
      if (streamDataCache[id]) {
        streamDataCache[id].isCompleted = true
      }
    })
    runningRequestCount = 0
    ElMessage.info('已停止所有流式请求')
  }
}

// ---------------------- 调用示例 ----------------------
// 批量请求列表
const batchRequests = [
  { url: '/api/stream/ai', headers: {}, data: { prompt: '介绍SSO单点登录' } },
  { url: '/api/stream/ai', headers: {}, data: { prompt: '介绍Token无感刷新' } },
  { url: '/api/stream/ai', headers: {}, data: { prompt: '介绍SSE流式请求' } },
  { url: '/api/stream/ai', headers: {}, data: { prompt: '介绍asyncPool并发控制' } }
]

// 执行批量请求（限制最大并发数2）
batchStreamRequest(batchRequests, 2, (requestId, fullResult) => {
  // 单个请求完成后的回调：拿到拼接好的完整结果
  console.log(`请求${requestId}完成，完整结果：`, fullResult)
  // 这里可以做后续处理：渲染、入库等
})

前端 PDF 导出：从文件流下载到自动分页

掘金前端

作者许留山

2026年3月17日 17:14

在工作中，我们经常会遇到需要生成 PDF 的业务，比如合同、报告等。

前后端合作

对于前端来说，最省事的就是后端生成 PDF 文件，前端根据返回的 URL 地址进行下载。

URL 下载

如果后端直接返回一个可访问的 URL 地址，我们可以通过以下几种方式进行下载：

1. 使用 `window.open` 或 `location.href`

这是最简单的方式，但缺点是无法控制下载后的文件名，且受浏览器拦截政策影响。

const downloadByUrl = (url: string) => {
  window.open(url, '_blank')
}

2. 使用 `<a>` 标签（推荐）

通过创建虚拟锚点并利用 download 属性，可以更好地控制下载行为。

/**
 * 通过 URL 下载文件
 * @param url 文件地址
 * @param fileName 自定义文件名
 */
export const downloadFileByUrl = (url: string, fileName?: string) => {
  const link = document.createElement('a')
  link.href = url

  // 如果提供了文件名，则设置 download 属性
  if (fileName) {
    link.download = fileName
  }

  link.target = '_blank'
  link.style.display = 'none'
  document.body.appendChild(link)

  link.click()

  // 清理
  document.body.removeChild(link)
}

文件流下载

如果后端返回的是文件流（Blob），由于浏览器无法直接解析这种数据格式作为下载源，我们需要通过 URL.createObjectURL 将其转换为一个临时的 blob:URL，然后利用 <a> 标签触发下载。

/**
 * 通过文件流下载文件
 * @param data 文件流数据 (Blob | ArrayBuffer | string)
 * @param fileName 下载后的文件名
 * @param mimeType 文件的 MIME 类型 (可选，如果不传则尝试从 data 中获取或使用默认值)
 */
export const downloadFileByStream = (data: any, fileName: string, mimeType?: string) => {
  // 1. 优先获取数据的类型
  const type = mimeType || (data instanceof Blob ? data.type : 'application/octet-stream')

  // 2. 将数据封装为 Blob 对象
  const blob = data instanceof Blob ? data : new Blob([data], { type })

  // 3. 创建一个临时的 URL 指向该 Blob 对象
  const blobURL = window.URL.createObjectURL(blob)

  // 4. 创建虚拟锚点触发下载
  const link = document.createElement('a')
  link.href = blobURL
  link.download = fileName
  link.style.display = 'none'
  document.body.appendChild(link)

  link.click()

  // 5. 下载执行后释放 URL 对象和 DOM 节点
  document.body.removeChild(link)
  // 不释放可能导致内存泄露，过早释放可能会导致下载失败，可以延迟触发
  window.URL.revokeObjectURL(blobURL)
}

前端生成 PDF

在有些业务上，需要纯前端生成 PDF。

`window.print()` 方法

这是调用浏览器原生打印功能最简单的方法。它会将当前页面的内容渲染到打印预览窗口中，用户可以选择保存为 PDF。

其实并不推荐，因为在很多复杂的结构中，需要做很多工作，才能达到理想的效果。并且会有打印预览弹窗，无法实现无感打印。

const handlePrint = () => {
  window.print()
}

CSS 控制

为了让打印出来的效果更好，我们通常需要使用 @media print 查询来控制打印时的样式。

@media print {
  /* 隐藏不需要打印的元素，如导航栏、侧边栏、按钮 */
  .no-print {
    display: none !important;
  }

  /* 调整打印区域的宽度 */
  .print-container {
    width: 100%;
    margin: 0;
    padding: 0;
  }

  /* 强制分页 */
  .page-break {
    page-break-after: always;
  }
}

`html2canvas-pro` + `jsPDF`

html2canvas 可以将网页内容转换为图片，然后 jsPDF 可以将图片转换为 PDF。

html2canvas-pro 是 html2canvas 的加强版分叉，完全兼容原版 API。它可以作为无缝替代品直接安装并导入（只需将 import html2canvas from 'html2canvas' 改为 import html2canvas from 'html2canvas-pro'）。它修复了原版在处理现代 CSS（如 object-fit、clip-path）时的许多渲染 Bug。

下面是通用的代码，可用于 95% 的场景，该方法会自动分页，且不会切断元素。

import html2canvas from 'html2canvas-pro' // 推荐使用 pro 版本无缝替代
import jsPDF from 'jspdf'

/**
 * 将指定 DOM 导出为 PDF
 * @param domId 目标 DOM 元素的 ID
 * @param title 导出的文件名
 */
export const exportPdf = async (domId: string, title?: string): Promise<void> => {
  const ele = document.getElementById(domId)
  if (!ele) throw new Error('未找到目标元素')

  const scale = window.devicePixelRatio > 1 ? window.devicePixelRatio : 2

  // 获取所有防截断元素（防止元素被分页切开，如表格行、标题、段落等）
  const nodes = ele.querySelectorAll('tr, h2, h3, h4, h5, p, img')
  const containerRect = ele.getBoundingClientRect()

  // 同时收集元素的 top 和 bottom 坐标
  const breakPointsPx = Array.from(nodes).map((node) => {
    const rect = node.getBoundingClientRect()
    return {
      top: rect.top - containerRect.top,
      bottom: rect.bottom - containerRect.top,
    }
  })

  // 生成画布
  const canvas = await html2canvas(ele, {
    scale,
    useCORS: true, // 允许图片跨域
    backgroundColor: '#ffffff',
  })

  const imgDataUrl = canvas.toDataURL('image/jpeg', 1.0)

  // 初始化 PDF 对象：p-竖向，pt-点(单位)，a4-纸张规格
  const pdf = new jsPDF('p', 'pt', 'a4')
  const a4Width = pdf.internal.pageSize.getWidth()
  const a4Height = pdf.internal.pageSize.getHeight()

  // 计算图片缩放比例：根据宽度适配 A4
  const ratio = a4Width / canvas.width
  const imgWidth = a4Width
  const imgHeight = canvas.height * ratio

  // 将坐标单位从 px 转换为 pt (符合 PDF 内部计算)
  const breakPointsPt = breakPointsPx.map((bp) => ({
    top: bp.top * ratio,
    bottom: bp.bottom * ratio,
  }))

  const topMargin = 30 // 页眉预留
  const bottomMargin = 30 // 页脚预留
  const pageContentHeight = a4Height - topMargin - bottomMargin

  let currentRenderY = 0 // 已完成渲染的 Y 轴偏移

  while (currentRenderY < imgHeight) {
    let expectedPageBottom = currentRenderY + pageContentHeight
    let actualPageBottom = expectedPageBottom

    // 判断是不是最后一页
    if (expectedPageBottom >= imgHeight) {
      actualPageBottom = imgHeight
    } else {
      // 只有不是最后一页，才去遍历判断是否被截断
      for (let i = 0; i < breakPointsPt.length; i++) {
        const { top, bottom } = breakPointsPt[i]

        // 核心判断：元素的头在当前页，但尾巴超出了当前页的底部，说明被“腰斩”了
        if (top > currentRenderY && top < expectedPageBottom && bottom > expectedPageBottom) {
          actualPageBottom = top // 在被截断元素的顶部切一刀，将其整体推到下一页
          break
        }
      }
    }

    if (actualPageBottom === currentRenderY) actualPageBottom = expectedPageBottom

    // 1. 渲染当前页图像（利用负偏移显示指定区域）
    pdf.addImage(imgDataUrl, 'JPEG', 0, topMargin - currentRenderY, imgWidth, imgHeight)

    // 2. 顶部遮罩（覆盖负偏移区域产生的重叠部分）
    if (currentRenderY > 0) {
      pdf.setFillColor(255, 255, 255)
      pdf.rect(0, 0, a4Width, topMargin, 'F')
    }

    // 3. 底部遮罩（留白并遮挡截断处的残影）
    const currentRenderBottomY = topMargin + (actualPageBottom - currentRenderY)
    pdf.setFillColor(255, 255, 255)
    pdf.rect(0, currentRenderBottomY, a4Width, a4Height - currentRenderBottomY, 'F')

    currentRenderY = actualPageBottom

    // 如果还没画完，添加新的一页
    if (currentRenderY + 5 < imgHeight) {
      pdf.addPage()
    }
  }
  const fileName = title ? `${title}_${Date.now()}` : Date.now().toString()
  pdf.save(`${fileName}.pdf`)
}

CodeSandbox 案例

用法案例

在 React 中使用该方案：

import { exportPdf } from './utils/pdf'

const ReportPage = () => {
  const handleDownload = async () => {
    try {
      // 传入容器 ID 和文件名
      await exportPdf('pdf-content', '月度分析报告')
    } catch (error) {
      console.error('生成 PDF 失败:', error)
    }
  }

  return (
    <div>
      <button onClick={handleDownload}>下载报告</button>

      {/* 这里的 ID 必须与 exportPdf 传入的一致 */}
      <div id="pdf-content" style={{ padding: '20px', background: '#fff' }}>
        <h2>报表标题</h2>
        <p>这里是很长很长的内容，可能会跨页...</p>
        <table>
          <tbody>
            <tr>
              <td>数据行 1</td>
            </tr>
            {/* 这里的 tr 会被防截断逻辑自动推送到下一页容器中 */}
            <tr>
              <td>数据行 2</td>
            </tr>
          </tbody>
        </table>
      </div>
    </div>
  )
}

进阶：PDF 模板架构设计

当项目中需要管理多个 PDF 模板时，建议采用“容器与显示分离”的架构，这样可以保证模板的纯净度（只负责 UI），同时方便在后台静默生成 PDF。

1. 目录结构建议

src/
  ├── components/
  │   └── pdf-templates/      # 所有的 PDF UI 模板
  │       ├── Contract.tsx    # 合同模板
  │       ├── Invoice.tsx     # 发票模板
  │       └── index.ts        # 统一导出
  └── utils/
      └── pdf.ts              # 核心 exportPdf 方法

2. 模板编写建议

模板组件应该只接收 data Props，不处理任何业务逻辑。

// src/components/pdf-templates/ContractTemplate.tsx
interface IProps {
  data: any
}

export const ContractTemplate = ({ data }: IProps) => (
  <div id="pdf-render-target" style={{ width: '800px', padding: '40px' }}>
    <h1>{data.title}</h1>
    {/* 自由编写复杂的 PDF 样式 */}
  </div>
)

3. 数据获取与导出架构

推荐在需要导出 PDF 的页面中，通过一个隐藏的“渲染容器”来实现。这样可以在不影响主页面 UI 的情况下，获取最新的业务数据并生成 PDF。

// src/pages/OrderDetails.tsx
import { useState } from 'react'
import { createPortal } from 'react-dom'
import { exportPdf } from '../utils/pdf'
import { ContractTemplate } from '../components/pdf-templates'

const OrderDetails = () => {
  const [isExporting, setIsExporting] = useState(false)
  const [data, setData] = useState(null)

  const startExport = async () => {
    setIsExporting(true)

    // 1. 获取业务数据 (如从 API 获取)
    const res = await fetchOrderData()
    setData(res)

    // 2. 等待 React 渲染 DOM (利用 setTimeout 确保渲染完成)
    setTimeout(async () => {
      try {
        await exportPdf('pdf-render-target', '业务合同')
      } finally {
        setIsExporting(false)
      }
    }, 100)
  }

  return (
    <div>
      <button onClick={startExport} disabled={isExporting}>
        {isExporting ? '正在生成...' : '下载 PDF'}
      </button>

      {/* 通过 Portal 将模板渲染在屏幕外，实现“无感”生成 */}
      {isExporting &&
        data &&
        createPortal(
          <div style={{ position: 'absolute', left: '-9999px', top: 0 }}>
            <ContractTemplate data={data} />
          </div>,
          document.body
        )}
    </div>
  )
}

4. 架构优势

关注点分离：页面只管触发，模板只管绘制，utils 只管转换。
数据解耦：PDF 模板的数据可以由父页面统一注入，也可以在 exportPdf 调用前按需加载。
用户无感：通过 createPortal 将渲染目标移出可视区域，用户在页面上感知不到“截图”的过程。

OpenClaw github 技能：让 GitHub 操作像聊天一样简单

掘金前端

作者少卿

2026年3月17日 17:08

作为前端开发者，我们每天要在 IDE、GitHub、终端、文档之间反复切换。创建 Issue、提 PR、查代码历史、追 Actions 状态……这些机械操作消耗了大量注意力。

OpenClaw 的 github 技能彻底改变了这个现状。它让你用自然语言直接操作 GitHub，无需记忆 gh CLI 命令，无需打开浏览器，在终端里一句话就能完成复杂协作。

一、技能定位

github 是 OpenClaw 官方维护的基础设施级技能，提供 GitHub 全栈自动化能力。它与 summarize 技能并称"效率双子星"，是前端开发者必装的核心工具。

核心价值：

🎯 意图驱动：说人话，不用背命令
⚡ 上下文保留：在开发流程中无缝集成 GitHub 操作
🔗 生态联动：与 summarize、react 等技能组合威力倍增

二、安装与授权

快速安装

# 官方源安装
clawhub install github

# 国内镜像（如遇 rate limit）
clawhub install github --registry https://clawhub-mirror.aliyuncs.com

首次授权

# 方式一：交互式登录
clawhub login

# 方式二：环境变量（CI/CD 场景）
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

Token 权限建议：

开发场景	所需权限	说明
个人开源项目	`public_repo`	仅操作公开仓库
团队私有项目	`repo`	读写私有仓库代码
自动化部署	`repo` + `workflow`	修改 Actions 配置

安全提示：使用 Fine-grained PAT，仅授权必要仓库，定期轮换 Token。

三、前端开发实战场景

场景 1：Issue 驱动开发（IDD）

从需求文档直接生成开发任务：

openclaw chat "读取产品需求文档，
用 github 技能创建 5 个开发 Issue：

1. [UI] 实现响应式导航栏 - Priority: High
2. [Feature] 集成 JWT 登录 - Priority: High  
3. [API] 封装用户管理接口 - Priority: Medium
4. [Test] 编写登录流程 E2E 测试 - Priority: Medium
5. [Deploy] 配置生产环境部署 - Priority: Low

每个 Issue 包含：
- 验收标准（3-5 条可验证项）
- 预估工时
- 关联标签：frontend, sprint-1
- 分配给 @frontend-team"

效果：需求文档 → 结构化开发任务，5 秒完成，无需手动复制粘贴。

场景 2：PR 自动化工作流

2.1 智能创建 PR

openclaw chat "用 github 技能为当前分支创建 PR：
- 标题：使用 conventional commits 格式（feat:/fix:/refactor:）
- 描述包含：
  * 变更摘要（自动读取 commit history）
  * 截图占位区（提示上传）
  * Breaking changes 说明（如有）
  * 测试覆盖情况
- 分配审查者：@tech-lead @senior-frontend
- 添加标签：needs-review, frontend
- 关联相关 Issue（自动检测 commit 中的 #issue 编号）"

2.2 审查辅助（与 `summarize` 联动）

openclaw chat "获取 PR #42 的代码变更，
用 summarize 技能生成审查清单：

---
📊 变更概览
- 影响文件：12 个
- 新增代码：+340 行
- 删除代码：-120 行
- 测试文件：3 个

🔍 审查要点
1. [性能] 检查 useEffect 依赖项是否正确
2. [安全] 验证用户输入是否有 XSS 过滤
3. [样式] 确认 Tailwind 类名未硬编码颜色值

⚠️ 潜在风险
- 第 45 行直接操作 DOM，建议改用 ref
- 新增 API 调用未设置超时处理

✅ 通过标准
- [ ] 所有审查点已检查
- [ ] CI 全部通过
- [ ] 至少 2 人批准
---"

场景 3：每日站会自动化

黄金组合：github + summarize

openclaw chat "用 github 技能查询昨日数据：
- 合并的 PR（作者、标题、影响范围）
- 关闭的 Issue（类型分布：bug/feature/docs）
- 今日待合并 PR 清单
- 代码提交热力图（可选）

用 summarize 技能生成站会报告，格式：

---
📅 2024-03-15 开发日报

✅ 昨日交付（3 项）
| PR | 作者 | 说明 | 影响 |
|----|------|------|------|
| #123 | @alice | 重构登录表单 | 修复内存泄漏 |
| #124 | @bob | 升级 React 18 | 并发特性就绪 |

🎯 今日计划（2 项待合并）
- #125 支付页面 UI（需 @tech-lead 审查）
- #126 优化首屏加载（CI 运行中）

⚠️ 阻塞问题
- #127 等待后端 API 文档更新 → @backend-team

📈 数据亮点
- 代码审查平均耗时：4.2 小时 ↓ 20%
- 测试覆盖率：82% ↑ 5%
---"

效果：每日早晨一句话，自动生成数据驱动的站会报告。

场景 4：代码追溯与故障排查

# 快速定位问题代码
openclaw chat "github 搜索 'useEffect' 在 src/hooks/ 目录的使用，
找出最近 2 周内新增且未添加 cleanup 函数的调用"

# 查看文件历史
openclaw chat "github 查看 src/utils/api.ts 的 blame 记录，
找出引入 axios 拦截器的那次提交，
并显示当时的 PR 描述和审查意见"

# 对比发布版本
openclaw chat "github 比较 v1.2.0 和 v1.3.0 的差异，
用 summarize 技能生成面向产品经理的变更说明（非技术语言）"

四、高级组合技

组合 1：自动化发布流水线

# 安装配套技能
clawhub install github summarize

# 执行发布
openclaw chat "执行发布流程：
1. github 检查 main 分支 CI 状态
2. github 对比上次 tag，用 summarize 生成 changelog
3. github 创建 Release v1.3.0，附带 changelog
4. github 触发 Actions 工作流：部署到生产环境
5. 在 Slack 频道发送发布通知（含变更摘要）"

组合 2：智能代码审查门禁

openclaw chat "检查当前 PR 是否满足合并条件：

1. github 检查 CI 状态（Actions 全部通过？）
2. github 检查审查批准（≥2 人？是否包含 Tech Lead？）
3. github 检查冲突（可自动 rebase？）
4. github 检查提交信息（符合 conventional commits？）

输出：
- 合规状态：✅ 通过 / ❌ 阻塞
- 阻塞项清单（如有）
- 建议操作（如 '请 @alice 审查' 或 '需要 rebase'）"

组合 3：开源项目维护

# 批量处理社区贡献
openclaw chat "github 查询本周新提交的 PR（状态：待审查），
按影响范围分类：
- 文档改进 → 快速合并
- Bug 修复 → 优先审查  
- 新功能 → 评估是否符合路线图

用 summarize 技能为每个 PR 生成一句话评估建议，
并自动添加标签：docs/bug/feature，分配审查者"

五、常用指令速查表

表格

意图	自然语言指令	传统 CLI 等价
创建仓库	`"github 创建私有仓库 react-dashboard，添加 README 和 MIT 许可证"`	`gh repo create ...`
提交 Issue	`"github 创建 Bug：登录页在 Safari 下白屏，标签 bug, priority-high"`	打开浏览器手动填写
创建 PR	`"github 从当前分支创建 PR，标题用 conventional commits"`	`gh pr create ...`
审查查询	`"github 显示 PR #123 的审查状态和冲突情况"`	`gh pr view ...` + `gh pr checks ...`
代码搜索	`"github 搜索项目中所有 console.log 未删除的位置"`	`gh search code ...`
发布管理	`"github 创建 Release v2.0.0，生成对比报告"`	多步骤手动操作

六、安全与最佳实践

Token 管理

# 检查当前授权状态
clawhub whoami

# 安全轮换 Token
clawhub logout && clawhub login

敏感操作确认

# 高风险操作（如删除仓库、强制推送）建议开启确认
openclaw chat "github 删除仓库 --confirm"
# 或配置环境变量：OPENCLAW_CONFIRM_DANGEROUS=true

审计日志

# 查看最近操作记录（用于排查问题）
openclaw chat "显示我最近 10 次 github 技能的操作日志"

七、故障排查

现象	原因	解决
`401 Bad credentials`	Token 过期或无效	`clawhub login` 重新授权
`403 Resource not accessible`	Token 权限不足	在 GitHub 设置中添加 `repo` 权限
`404 Not Found`	仓库不存在或无权访问	检查仓库名拼写和权限
操作超时	网络或 API 延迟	重试或检查 GitHub Status
Rate limit	请求过于频繁	使用 `GITHUB_TOKEN` 或等待重置

八、参考资源

资源	获取方式
官方文档	`docs.openclaw.ai`
技能市场	`clawhub.ai` / `clawhub.com`
CLI 帮助	`clawhub --help` / `clawhub github --help`
安全审计	`clawsecure.ai`

总结

github 技能将 GitHub 从"需要专门操作的网站"转变为"开发流程的自然延伸"。对于前端开发者，它特别适合：

✅ 敏捷迭代：Issue/PR 快速创建，减少上下文切换成本
✅ 代码质量：自动化审查清单，确保交付标准
✅ 团队协作：数据驱动的日报/周报，信息透明同步
✅ 开源维护：批量处理社区贡献，提升维护效率

推荐安装组合：

# 前端开发黄金套装（效率三件套）
clawhub install github summarize self-improving-agent

# 完整工作流（可选）
clawhub install react-component-generator frontend-performance browser-devtools-inspector

立即体验：

clawhub install github
openclaw chat "github 查看我的最近 Issue"

普通视图

目录

Why：为什么需要宏？

宏解决的核心问题

What：宏是什么？

Rust 宏的家族树

核心概念：TokenStream

How：如何使用宏？

1. 声明宏 (macro_rules!)

1.1 基础语法

1.2 接受参数

1.3 多模式匹配

1.4 实战案例：类型安全的单位转换

2. 派生宏 (Derive Macros)

2.1 工作原理

2.2 创建自定义派生宏

2.3 处理泛型和生命周期

3. 属性宏 (Attribute Macros)

3.1 基础结构

3.2 实战：创建一个计时宏

3.3 高级案例：带参数的属性宏

4. 函数式宏 (Function-like Macros)

4.1 基础示例

4.2 实战：HTML 模板宏

最佳实践

1. 命名规范

2. 错误处理

3. 卫生性（Hygiene）

4. 文档化你的宏

5. 测试宏

6. 性能考虑

常见误区

误区 1：宏可以做任何事

误区 2：忽略宏的顺序依赖

误区 3：过度使用宏

误区 4：不处理边界情况

误区 5：忘记递归限制

调试技巧

1. 查看宏展开结果

2. 使用 dbg! 宏

3. 编译时打印

实战综合案例：创建一个状态机宏

总结

✅ 使用宏的好时机

❌ 避免使用宏的情况

🎯 学习路径建议

📚 推荐资源

原文地址

1. 为什么需要系统化的AI配置

1.1 传统方式的痛点

1.2 系统化配置能做什么

2. 核心概念一览

3. MCP：给AI装上"手"和"脚"

3.1 MCP是什么

3.2 怎么理解MCP

3.3 安装MCP

3.4 常用MCP推荐

4. Rules：制定"项目宪法"

4.1 Rules是什么

4.2 怎么理解Rules

4.3 配置Rules

4.4 怎么使用Rules

5. Skills：召唤"领域专家"

5.1 Skills是什么

5.2 怎么理解Skills

5.3 配置Skills

5.4 怎么使用Skills

6. Agents：分配"专人负责"

6.1 Agents是什么

6.2 怎么理解Agents

6.3 配置Agents

6.4 怎么使用Agents

7. Hooks：设置"自动触发"

7.1 Hooks是什么

7.2 怎么理解Hooks

7.3 配置Hooks

8. 怎么组合使用

8.1 一个典型的工作流

8.2 组合使用示例

总结

2. 使用 `dbg!` 宏

3. `fixed` 定位元素在键盘弹起时失效

4. Android `windowSoftInputMode` 的影响

6. iOS `input` 框获得焦点时页面缩放

8. iOS WebKit 的 `interactive-widget=resizes-content` 方案（现代方案）