该渲染由 Shiro API 生成，可能存在排版问题，最佳体验请前往：https://xming.cyou/posts/devops/quicker

# 注意替换安装路径， 你也可以在 -e 后面接 -s 静默安装
winget install --id=LiErHeXun.Quicker -e --location "D:\Program Files\Quicker"

看完了？说点什么呢

该渲染由 Shiro API 生成，可能存在排版问题，最佳体验请前往：https://xming.cyou/posts/devops/pve

安装完成后如上图所示，系统会给出图形化访问地址（`https://IP地址:8006`）。后续的主要操作都在这个 Web 控制台中完成。到这里，PVE 系统已经安装完成，下面进入初始化与资源规划。

sed -i 's/^deb/# deb/g' /etc/apt/sources.list.d/pve-enterprise.list

cat > /etc/apt/sources.list <<'EOF'
deb https://mirrors.ustc.edu.cn/debian/ bookworm main contrib non-free non-free-firmware
deb https://mirrors.ustc.edu.cn/debian/ bookworm-updates main contrib non-free non-free-firmware
deb https://mirrors.ustc.edu.cn/debian-security bookworm-security main contrib non-free non-free-firmware
EOF

cat > /etc/apt/sources.list.d/pve-no-subscription.list <<'EOF'
deb http://download.proxmox.com/debian/pve bookworm pve-no-subscription
EOF

apt update && apt full-upgrade -y
reboot

cp /usr/share/javascript/proxmox-widget-toolkit/proxmoxlib.js{,.bak}
sed -Ezi.bak "s/(Ext.Msg.show\\(\\{\\s+title: gettext\\('No valid sub)/void\\(\\{ \\/\\/\\1/g" /usr/share/javascript/proxmox-widget-toolkit/proxmoxlib.js
systemctl restart pveproxy

adduser adminops
usermod -aG sudo adminops

PermitRootLogin prohibit-password
PasswordAuthentication no # 关闭ssh密码认证
PubkeyAuthentication yes # 开启ssh密钥登录

systemctl restart ssh

timedatectl set-timezone Asia/Shanghai
timedatectl status
hostnamectl status

auto lo
iface lo inet loopback

# 物理网卡不直接配 IP，交给网桥 vmbr0 使用
iface eno1 inet manual

# 管理网桥：PVE 管理 IP 建议配在这里
auto vmbr0
iface vmbr0 inet static
    address 192.168.10.10/24    # 按你的管理网段修改（示例：10.0.0.10/24）
    gateway 192.168.10.1        # 按你的网关修改（示例：10.0.0.1）
    bridge-ports eno1           # 按你的物理网卡名修改（可能是 enp3s0 / eno2）
    bridge-stp off              # 家用/中小场景通常关闭 STP；复杂二层网络可按需开启
    bridge-fd 0                 # 转发延迟，保持默认 0

ifreload -a

auto vmbr0
iface vmbr0 inet static
    address 192.168.10.10/24
    gateway 192.168.10.1
    bridge-ports eno1
    bridge-stp off
    bridge-fd 0
    bridge-vlan-aware yes       # 开启 VLAN 感知（前提：交换机端口允许对应 VLAN）
#   bridge-vids 10 20 30        # 可选：限制只允许通过的 VLAN

# Intel 平台（任选其一，不要混用）
GRUB_CMDLINE_LINUX_DEFAULT="quiet intel_iommu=on iommu=pt"

# AMD 平台（任选其一，不要混用）
GRUB_CMDLINE_LINUX_DEFAULT="quiet amd_iommu=on iommu=pt"

update-grub
reboot

dmesg | grep -E "DMAR|IOMMU"

lspci -nn
find /sys/kernel/iommu_groups/ -type l

lspci -nn | grep -Ei "vga|3d|nvidia|amd|ethernet|sas"

echo "options vfio-pci ids=10de:1eb8,10de:10f8" > /etc/modprobe.d/vfio.conf
echo -e "vfio\nvfio_iommu_type1\nvfio_pci\nvfio_virqfd" > /etc/modules-load.d/vfio.conf
update-initramfs -u -k all
reboot

lspci -nnk -d 10de:1eb8

rm -f /etc/modprobe.d/vfio.conf /etc/modules-load.d/vfio.conf
update-initramfs -u -k all
reboot

看完了？说点什么呢

该渲染由 Shiro API 生成，可能存在排版问题，最佳体验请前往：https://xming.cyou/posts/devops/htttp-proxy

# version: '3'
services:
  mihomo: 
    container_name: mihomo
    image: metacubex/mihomo:latest
    restart: unless-stopped
    privileged: true # 开启特权模式（TUN 模式最简单的方式）
    pid: host # 共享 PID 命名空间（便于调试和进程管理）
    ipc: host # 共享 IPC 命名空间
    network_mode: host # 使用宿主机网络栈（性能最优，TUN 必需）
    cap_add:
      - ALL
    security_opt:
      - apparmor=unconfined # 禁用 AppArmor 限制（某些系统需要）
    volumes:
      - ~/.mihomo/config:/root/.config/mihomo
      - /dev/net/tun:/dev/net/tun # TUN 设备（TUN 模式必需）
      # 共享host的时间环境
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro

  # mihomo内置的有管理界面，也挺好用，如果不想额外折腾，下面可以删掉
  metacubexd: 
    container_name: metacubexd
    image: ghcr.io/metacubex/metacubexd
    restart: unless-stopped
    # 网络配置（与 mihomo 分离，仅提供 Web 访问）
    network_mode: bridge
    # 依赖 mihomo 服务（确保顺序启动）
    depends_on:
      mihomo:
    ports:
      - '127.0.0.1:28002:80'
    volumes:
      - ~/.mihomo/caddy:/config/caddy:rw
      # 共享host的时间环境
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro

看完了？说点什么呢

为什么选择 go:embed

• 编译期打包：资源在构建阶段入库，运行期无需磁盘依赖与路径探测。
• 原生 API：无需第三方库，标准库 embed、io/fs、net/http 即可使用。
• 一致的跨平台行为：统一使用正斜杠路径，避免 Windows/Unix 差异。
• 更安全可控：避免运行期“配置文件不在预期位置”导致的故障。

快速上手：单文件、目录与多文件

嵌入单个文本文件为字符串：

package main

import (
    _ "embed"
    "fmt"
)

//go:embed message.txt
var message string

func main() {
    fmt.Println(message)
}

嵌入目录并读取文件（以嵌入根为基准路径）：

package main

import (
    "embed"
    "fmt"
)

//go:embed static
var staticFiles embed.FS

func main() {
    data, _ := staticFiles.ReadFile("static/index.html")
    fmt.Println(string(data))
}

使用通配符一次性嵌入多文件：

package main

import (
    "embed"
    "fmt"
)

//go:embed templates/*.html partials/*.html
var tmplFS embed.FS

func main() {
    entries, _ := tmplFS.ReadDir("templates")
    for _, e := range entries {
        b, _ := tmplFS.ReadFile("templates/" + e.Name())
        fmt.Printf("Loaded %s (%d bytes)\n", e.Name(), len(b))
    }
}

用于 Web：内嵌静态资源即开即用

package main

import (
    "embed"
    "net/http"
)

//go:embed static/*
var assets embed.FS

func main() {
    http.Handle("/", http.FileServer(http.FS(assets)))
    http.ListenAndServe(":8080", nil)
}

运行后在 http://localhost:8080 直接访问嵌入的静态文件，无需额外拷贝。

二进制资源：图片、PDF、压缩包

package main

import (
    _ "embed"
    "fmt"
)

//go:embed image.webp
var img []byte

func main() {
    fmt.Printf("Image size: %d bytes\n", len(img))
}

当资源非 UTF-8 文本时，使用 []byte 可以避免编码问题。

路径与加载规则（重点答疑）

• 相对路径且仅限包内：//go:embed 的路径与模式必须为相对路径，基于“声明该变量的源文件所在目录”。不支持绝对路径。
• 统一分隔符：路径分隔一律使用正斜杠 /，即使在 Windows。示例："static/index.html"。
• 模式匹配：支持通配符（遵循 filepath.Match 语义），如 static/*、templates/*.html。可以在同一指令中列出多个模式。
• 不允许越级：路径中不能包含 ..，不可引用包目录之外的文件。
• 嵌入内容类型：可以嵌入任何常规文件类型。按变量类型区分读取方式：string（文本）、[]byte（二进制）、embed.FS（多文件/目录）。
• FS 读取相对嵌入根：使用 embed.FS 时，ReadFile 的路径以嵌入根为基准；若嵌入的是目录 static，读取应为 static/xxx。
• 构建与可见性：嵌入在构建期完成；资源更新后需重新编译。仅能嵌入构建系统可见的常规文件，符号链接不会被跟随。

结论：

• 是否支持相对和绝对路径？仅支持相对路径（相对源文件目录），不支持绝对路径。
• 文件类型支持情况？任意常规文件均可嵌入；文本建议用 string，二进制用 []byte；多文件/目录用 embed.FS。

常见陷阱与最佳实践

• 控制二进制体积：大文件会显著增大可执行文件；将超大资源改用外部 CDN/对象存储更合适。
• 保持路径一致性：在所有平台都用 /；不要混用反斜杠 \。
• 指令位置与类型匹配：//go:embed 必须紧邻变量声明；变量类型仅支持 string、[]byte、embed.FS。
• 多模式整合：将多个子目录合并到同一 embed.FS，减少散乱的变量。
• 变更需重编：资源文件变化后务必重新构建以更新嵌入内容。

一个更完整的模板渲染示例

package main

import (
    "embed"
    "html/template"
    "net/http"
)

//go:embed templates/*.html
var views embed.FS

func main() {
    t := template.Must(template.ParseFS(views, "templates/*.html"))
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        _ = t.ExecuteTemplate(w, "home.html", map[string]string{"Title": "Embed Demo"})
    })
    _ = http.ListenAndServe(":8080", nil)
}

小结

go:embed 让资源管理从“运行期找文件”变为“编译期打包”。掌握“相对路径、统一分隔符、类型选择”这三点，就能在 CLI、Web 服务、微服务工具中干净地管理静态与模板资源，极大简化部署与加载流程。

为什么选择 SSE

• 面向“服务器→浏览器单向推送”的场景，浏览器原生支持 EventSource，无需第三方库
• 基于标准 HTTP（含 HTTP/2），与现有网关、负载均衡、鉴权、缓存体系兼容度高
• 自动断线重连与消息续传（Last‑Event‑ID）由浏览器内置完成
• 只需文本数据，天然适合通知、进度、日志、监控等单向推送

原理与协议

• 连接与建立
  客户端通过 EventSource 发起 GET 请求，请求头隐式包含 Accept: text/event-stream；服务器以 Content-Type: text/event-stream 响应并保持连接打开，通过持续的 HTTP 响应流推送数据。
• 事件格式
  一条事件由多行键值对组成并以连续两个换行符结束。常见字段：
  • event: 事件类型，默认是 message
  • data: 消息主体数据（可多行，每行一个 data:）
  • id: 事件唯一标识（用于断线续传）
  • retry: 重连时间间隔（毫秒） 示例： data: This is a message

或带事件类型与 JSON 数据：

  event: userupdate
  data: {"username":"john_doe","status":"online"}
  

• 断线重连
  浏览器自动重试，若服务器曾发送 id:，浏览器在重连时携带 Last-Event-ID，服务器可从该 ID 之后继续发送。
• 保活与代理
  许多代理会因长时间无数据而断开，服务器可定期发送注释行（以冒号起始，如 : keepalive）作为保活。建议设置 Cache-Control: no-cache、Connection: keep-alive，必要时对部分代理设置 X-Accel-Buffering: no。

SSE 与 WebSocket 对比

• 通信模型
  
  • SSE：服务器→浏览器单向文本流，浏览器原生 EventSource，自动重连与续传
  • WebSocket：在独立的 TCP 连接上建立全双工通信，使用协议升级与帧（frame）进行数据传输，需自行处理重连与续传
• 基础设施与兼容性
  
  • SSE：走标准 HTTP，易穿透与复用现有网关、鉴权、中间件；适合通知、状态推送、日志流
  • WebSocket：适合 IM、协作编辑、游戏等强双向低延时场景
• 性能与实现
  
  • SSE：实现简单、成本低；消息量大或需要二进制时不适用
  • WebSocket：灵活强大，但实现与维护复杂度更高

后端

package main

import (
    "encoding/json"
    "io"
    "log"
    "net/http"
    "strconv"
    "strings"
    "time"

    "github.com/r3labs/sse/v2"
)

func main() {
    // 创建 SSE 服务器与单一流（建议统一使用一个流，通过 event 类型区分）
    server := sse.New()
    server.CreateStream("events")

    mux := http.NewServeMux()
    mux.HandleFunc("/events", func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Access-Control-Allow-Origin", "*")
        server.ServeHTTP(w, r)
    })

    mux.HandleFunc("/publish", func(w http.ResponseWriter, r *http.Request) {
        // 支持通过 type 指定事件类型（默认 message），便于后端统一发布
        // 事件类型建议：
        // - message：文本通知，适合短消息或提示
        // - tick：时间戳字符串，适合心跳与时钟
        // - userupdate：JSON 用户状态，如 {"username":"john","status":"online"}
        // - stock：JSON 行情，如 {"symbol":"ACME","price":123.45}
        // - score：JSON 比分，如 {"home":1,"away":2}
        // - location：JSON 位置，如 {"lat":31.23,"lng":121.47}
        // - progress：JSON/数字进度，如 {"percent":42}
        // - system：文本系统事件，如 "ok" 或日志片段
        body, _ := io.ReadAll(r.Body)
        msg := strings.TrimSpace(string(body))
        if msg == "" {
            msg = r.URL.Query().Get("msg")
        }
        if msg == "" {
            http.Error(w, "msg required", http.StatusBadRequest)
            return
        }
        eventType := r.URL.Query().Get("type")
        if eventType == "" {
            eventType = "message"
        }
        server.Publish("events", &sse.Event{
            ID:    []byte(strconv.FormatInt(time.Now().UnixNano(), 10)),
            Event: []byte(eventType),
            Data:  []byte(msg),
        })
        w.WriteHeader(http.StatusNoContent)
    })

    go func() {
        // tick：时间戳字符串，适合心跳与时钟
        ticker := time.NewTicker(5 * time.Second)
        for t := range ticker.C {
            server.Publish("events", &sse.Event{
                ID:    []byte(strconv.FormatInt(time.Now().UnixNano(), 10)),
                Event: []byte("tick"),
                Data:  []byte(t.Format(time.RFC3339)),
            })
        }
    }()

    go func() {
        // stock：行情 JSON，适合实时价格或指标
        type Stock struct {
            Symbol string  `json:"symbol"`
            Price  float64 `json:"price"`
        }
        t := time.NewTicker(7 * time.Second)
        for tt := range t.C {
            _ = tt
            payload, _ := json.Marshal(Stock{Symbol: "ACME", Price: 123.45})
            server.Publish("events", &sse.Event{
                ID:    []byte(strconv.FormatInt(time.Now().UnixNano(), 10)),
                Event: []byte("stock"),
                Data:  payload,
            })
        }
    }()

    go func() {
        // score：比分 JSON，适合体育赛事
        type Score struct {
            Home int `json:"home"`
            Away int `json:"away"`
        }
        t := time.NewTicker(9 * time.Second)
        h, a := 0, 0
        for range t.C {
            h++
            payload, _ := json.Marshal(Score{Home: h, Away: a})
            server.Publish("events", &sse.Event{
                ID:    []byte(strconv.FormatInt(time.Now().UnixNano(), 10)),
                Event: []byte("score"),
                Data:  payload,
            })
        }
    }()

    go func() {
        // location：位置 JSON，适合地图轨迹
        type Location struct {
            Lat float64 `json:"lat"`
            Lng float64 `json:"lng"`
        }
        t := time.NewTicker(11 * time.Second)
        lat, lng := 31.2304, 121.4737
        for range t.C {
            lat += 0.0003
            lng += 0.0002
            payload, _ := json.Marshal(Location{Lat: lat, Lng: lng})
            server.Publish("events", &sse.Event{
                ID:    []byte(strconv.FormatInt(time.Now().UnixNano(), 10)),
                Event: []byte("location"),
                Data:  payload,
            })
        }
    }()

    go func() {
        // progress：进度（数字或 JSON），适合长任务状态
        type Progress struct {
            Percent int `json:"percent"`
        }
        for {
            for p := 0; p <= 100; p += 20 {
                payload, _ := json.Marshal(Progress{Percent: p})
                server.Publish("events", &sse.Event{
                    ID:    []byte(strconv.FormatInt(time.Now().UnixNano(), 10)),
                    Event: []byte("progress"),
                    Data:  payload,
                })
                time.Sleep(3 * time.Second)
            }
        }
    }()

    go func() {
        // system：系统事件文本，适合日志片段或健康检查
        t := time.NewTicker(30 * time.Second)
        for range t.C {
            server.Publish("events", &sse.Event{
                ID:    []byte(strconv.FormatInt(time.Now().UnixNano(), 10)),
                Event: []byte("system"),
                Data:  []byte("ok"),
            })
        }
    }()

    log.Fatal(http.ListenAndServe(":8080", mux))
}

前端

<script>
// 订阅统一流 events，根据不同 event 类型分别处理
const es = new EventSource("http://localhost:8080/events?stream=events");

// 默认事件类型 message：文本通知
es.onmessage = (e) => {
  console.log("message", e.data);
};
// tick：时间戳字符串
es.addEventListener("tick", (e) => {
  console.log("tick", e.data);
});
// stock：行情 JSON
es.addEventListener("stock", (e) => {
  try { console.log("stock", JSON.parse(e.data)); } catch { console.log(e.data); }
});
// score：比分 JSON
es.addEventListener("score", (e) => {
  try { console.log("score", JSON.parse(e.data)); } catch { console.log(e.data); }
});
// location：位置 JSON
es.addEventListener("location", (e) => {
  try { console.log("location", JSON.parse(e.data)); } catch { console.log(e.data); }
});
// progress：进度 JSON/数字
es.addEventListener("progress", (e) => {
  try { console.log("progress", JSON.parse(e.data)); } catch { console.log(e.data); }
});
// system：系统事件文本
es.addEventListener("system", (e) => {
  console.log("system", e.data);
});
</script>

// 组件中使用：将不同事件类型渲染到页面
const es = new EventSource("http://localhost:8080/events?stream=events");
es.onmessage = (e) => {
  const el = document.getElementById("out");
  if (el) el.textContent = e.data;
};
es.addEventListener("tick", (e) => {
  const el = document.getElementById("tick");
  if (el) el.textContent = e.data;
});
es.addEventListener("progress", (e) => {
  const el = document.getElementById("progress");
  try { const p = JSON.parse(e.data); if (el) el.textContent = p.percent + "%"; }
  catch { if (el) el.textContent = e.data; }
});

运行与测试

• 启动后端：go run main.go，监听 8080 端口
• 打开页面：在浏览器控制台观察事件输出

• 发布消息：POST 文本到 http://localhost:8080/publish?type=message 或 GET http://localhost:8080/publish?type=message&msg=hello，浏览器会收到 events 流的推送（根据 type 作为事件类型）

最佳实践与注意事项

• 保活与缓冲：周期性发送注释行维持连接活跃；必要时设置 X-Accel-Buffering: no
• 事件整形：多行数据逐行 data: 前缀；使用 id 支持断线续传（配合 Last-Event-ID）
• 并发与背压：为 client 通道设置有限缓冲并在广播时使用非阻塞写入；根据场景调整缓冲与丢弃策略
• 安全与鉴权：走标准 HTTP，可复用 Cookie、Token、签名等鉴权方式；若需鉴权刷新，结合短期令牌与重连策略

适用场景

• 实时通知与社交动态提示
• 股票行情与金融市场数据更新
• 体育赛事比分与统计实时更新
• 地理位置追踪与地图轨迹刷新
• 系统监控面板：服务器状态、日志流与指标
• 长任务进度、批处理状态、构建或部署流水输出
• 面板与监控看板的低频实时更新

参考文献

什么是 SSE？

SSE 和 WebSocket 的区别，差异对比

一、 深度剖析 Next.js 渲染模式

Next.js 的核心竞争力在于极其灵活的混合渲染机制。理解每种模式的 触发时机、数据流向 和 适用场景 是架构选型的基础。

1.1 渲染光谱 (The Rendering Spectrum)

1.2 App Router 下的范式转移：RSC vs CC

Next.js 13+ 引入的 App Router 彻底改变了组件模型，核心在于 React Server Components (RSC)。

React Server Components (RSC)

默认情况下，app 目录下的组件都是 RSC。

• 优势：
  • 零 Bundle Size：组件代码及其依赖（如大型日期库、Markdown 解析库）仅在服务端运行，不会被打包发送到浏览器。
  • 后端直连：可直接连接数据库、读取文件系统，无需经过 API Layer。
• 限制：无法使用 useState, useEffect, 无法绑定 DOM 事件 (onClick)。

实战：在 Server Component 中获取数据 Next.js 扩展了 fetch API，并支持在组件中直接使用 async/await。

// app/page.tsx (默认是 Server Component)
async function getData() {
  const res = await fetch('https://api.example.com/data', { 
    next: { revalidate: 3600 } // ISR: 每小时重新验证一次
  });
  if (!res.ok) throw new Error('Failed to fetch data');
  return res.json();
}

export default async function Page() {
  const data = await getData(); // 直接 await，像写后端代码一样简单

  return (
    <main>
      <h1>{data.title}</h1>
      <p>{data.content}</p>
    </main>
  );
}

Client Components (CC)

当且仅当你在文件顶部声明 'use client' 时，该组件及其导入的所有子组件才会成为 Client Component。

• 注意：Client Component 依然会在服务端进行预渲染 (Pre-rendering) 生成初始 HTML，然后在客户端进行 水合 (Hydration)。它不仅仅是 CSR。

最佳实践：叶子节点模式 (Leaf Pattern)

为了最大化 RSC 的优势，应尽量将 Client Component 推向组件树的末端（叶子节点）。

// ❌ 错误做法：在根布局就把整个应用变成 Client Component
// app/layout.tsx
'use client' 
export default function RootLayout({ children }) { ... }

// ✅ 正确做法：将交互逻辑隔离在独立组件中
// app/layout.tsx (Server Component)
import { SearchBar } from './SearchBar'; // SearchBar 是 Client Component

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <nav><SearchBar /></nav> {/* 只有 SearchBar 会打包 JS 发送给浏览器 */}
        <main>{children}</main>
      </body>
    </html>
  );
}

1.3 深度解析：水合 (Hydration)

水合是现代 React/Next.js 应用中最关键但也最容易被误解的概念。

什么是水合？

简单来说，水合是 React "接管" 服务端生成的静态 HTML 的过程。

1. 服务端 (SSR/SSG)：React 组件在服务器运行，生成 HTML 字符串。此时页面是静态的，按钮点击无反应。
2. 浏览器：下载并显示 HTML (FCP - First Contentful Paint)。
3. 下载 JS：浏览器下载 React 框架和组件代码。
4. 水合 (Hydration)：React 在客户端再次运行组件逻辑，生成虚拟 DOM，并与现有的真实 DOM 节点进行对比（Diff）。如果匹配，React 就会把事件监听器（Event Listeners）绑定到 DOM 上，使页面变得可交互。

常见灾难：水合不匹配 (Hydration Mismatch)

当服务端生成的 HTML 与客户端初次渲染的 HTML 不一致时，React 会抛出 Hydration Error，并强制客户端重新渲染整个节点，导致性能损耗和 UI 闪烁。

典型错误场景：

1. 时间戳/随机数： tsx // ❌ 服务端生成的时间与客户端渲染时的时间不一致 <div>{new Date().toLocaleTimeString()}</div> <div>{Math.random()}</div>
2. 浏览器特有 API： tsx // ❌ 服务端没有 window 对象，渲染出不同内容 <div>{typeof window !== 'undefined' ? 'Client' : 'Server'}</div>
3. HTML 嵌套错误：
   • <p> 标签里嵌套 <div>（这是非法的 HTML，浏览器会自动修复 DOM 结构，导致 React 找不到预期的节点）。

解决方案

1. 使用 useEffect 延迟渲染：确保逻辑只在客户端执行。

   const [mounted, setMounted] = useState(false);
   useEffect(() => setMounted(true), []);
   
   if (!mounted) return null; // 或返回加载占位符
   return <div>{window.innerWidth}</div>;
   

2. suppressHydrationWarning：如果你明确知道内容会不一致（如时间戳），可以强制 React 忽略警告。

   <time suppressHydrationWarning>{new Date().toLocaleTimeString()}</time>
   

二、 React Hooks 进阶与性能优化

Hooks 也就是 React 的"魔法"，但如果不理解其背后的 引用稳定性 (Referential Equality) 原理，极易导致性能灾难。

2.1 useMemo：不仅仅是缓存计算

很多开发者认为 useMemo 只是为了缓存昂贵的计算结果，其实它更重要的作用是 保持引用稳定。

核心场景

1. 昂贵的计算：避免每次渲染都跑一遍几千次循环。
2. 引用稳定性（关键）：当一个对象/数组被作为 子组件的 Props 或 其他 Hooks 的依赖项 时。

场景实战：避免副作用连锁反应

// ❌ 反例：每次父组件渲染，filterOptions 都会生成新的对象引用
const Parent = () => {
  const filterOptions = { role: 'admin', status: 'active' }; 
  
  // 导致 Child 即使被 React.memo 包裹也会重渲染
  // 导致 useEffect 即使逻辑没变也会再次触发
  return <Child options={filterOptions} />;
};

// ✅ 正确：锁定引用
const Parent = () => {
  const filterOptions = useMemo(() => ({ 
    role: 'admin', status: 'active' 
  }), []); // 依赖为空，整个生命周期引用不变
  
  return <Child options={filterOptions} />;
};

避坑指南

• 不要过度优化：useMemo 本身有开销。对于简单的 a + b 或者简单的字符串拼接，使用 useMemo 是负优化。

2.2 useCallback：函数引用的定海神针

useCallback 是 useMemo 的函数特化版本。

核心场景

1. 传递给 memo 化的子组件：如果子组件用 React.memo 优化了，但 props 里的函数每次父组件渲染都变，优化就会失效。
2. 作为 Hook 的依赖：比如自定义 Hook 需要接收一个回调函数。

场景实战：闭包陷阱 (Stale Closure)

这是 useCallback (以及 useEffect) 最容易出错的地方。

const [count, setCount] = useState(0);

// ❌ 陷阱：这个函数创建时捕获了当时的 count (比如 0)
// 如果依赖数组为空 []，无论后续 count 变成多少，log 出来的永远是 0
const handleLog = useCallback(() => {
  console.log('Current count:', count); 
}, []); // 缺少 count 依赖

// ✅ 修正方案 A：添加依赖
const handleLogFixed = useCallback(() => {
  console.log('Current count:', count);
}, [count]); // 每次 count 变了，生成新函数（这有时会违背初衷）

// ✅ 修正方案 B：使用 Ref 穿透闭包 (Ref Pattern)
// 当你既想保持函数引用不变，又想访问最新 state 时
const countRef = useRef(count);
useEffect(() => { countRef.current = count; }, [count]);

const handleLogAdvanced = useCallback(() => {
  console.log('Current count:', countRef.current);
}, []); // 永远不更新引用，但能拿到最新值

2.3 useEffect：副作用管理的艺术

最佳实践

1. 一个 Effect 做一件事：不要把数据获取、事件监听、DOM 操作塞在一个 useEffect 里。
2. 处理竞态条件 (Race Conditions)：在异步数据获取中非常常见。

useEffect(() => {
  let ignore = false;
  
  async function fetchProfile() {
    const result = await api.fetchUser(userId);
    // 如果组件卸载了，或者 userId 变了导致开启了新一轮 effect，
    // 这里的 ignore 就会变成 true，从而丢弃旧的请求结果
    if (!ignore) setProfile(result);
  }

  fetchProfile();

  return () => { ignore = true; };
}, [userId]);

2.4 useRef：脱离数据流的逃生舱

useRef 返回一个可变的 ref 对象，其 .current 属性被初始化为传入的参数。修改 .current 不会触发组件重新渲染。

核心场景

1. 访问 DOM 节点：最经典用法，操作 focus、scroll 等。
2. 存储 Mutable 变量：类似 Class 组件的 this.xxx 实例变量。
   • 存储定时器 ID。
   • 存储上一次的 Props 值用于对比 (Previous Value)。

// 场景：实现 usePrevious Hook
function usePrevious(value) {
  const ref = useRef();
  // 每次渲染都会执行，但在 return 之前更新
  // 所以本次渲染拿到的 ref.current 还是上次的值
  useEffect(() => {
    ref.current = value;
  }, [value]);
  return ref.current;
}

2.5 useLayoutEffect：同步 DOM 更新

签名与 useEffect 相同，但它会在所有的 DOM 变更之后 同步 调用。

核心场景

• 防止闪烁：当你需要测量 DOM 元素尺寸并根据尺寸重新调整布局时。
• 如果使用 useEffect，用户可能会先看到初始布局，然后瞬间跳变到新布局。useLayoutEffect 会阻塞浏览器绘制，直到执行完毕，确保用户只看到最终状态。

2.6 useImperativeHandle：定制暴露给父组件的实例值

应当尽量避免使用。但在某些场景（如封装复杂的 UI 库组件）下，你可能需要向父组件暴露特定的方法（如 focus(), scrollToBottom()），而不是整个 DOM 节点。

const FancyInput = forwardRef((props, ref) => {
  const inputRef = useRef();
  
  useImperativeHandle(ref, () => ({
    focus: () => {
      inputRef.current.focus();
    },
    // 只暴露 focus，不暴露其他原生 DOM 方法，更安全
  }));

  return <input ref={inputRef} />;
});

2.7 并发模式 Hooks (React 18+)

React 18 引入了并发渲染，带来了提升用户体验的新 Hooks。

useTransition

用于将某些状态更新标记为 "Transition" (非紧急更新)。

• 场景：输入框输入（紧急）导致的大列表过滤（非紧急）。
• 效果：保持 UI 响应，不会因为列表渲染阻塞输入框打字。

useDeferredValue

useTransition 是包装更新动作，useDeferredValue 是包装状态值本身。类似于防抖 (Debounce)，但更智能（由 React 调度决定延迟多久）。

const deferredQuery = useDeferredValue(query);
// 列表只依赖 deferredQuery，当 query 快速变化时，deferredQuery 会滞后更新
// 从而减少列表重渲染次数

三、 高级状态管理模式

随着应用复杂度增加，useState 往往力不从心，而引入 Redux 又显得过重。

3.1 Context + useReducer：轻量级 Redux

这种模式适合管理中等复杂度的全局状态（如主题、用户信息、购物车）。

性能痛点与优化

Context 有一个著名的性能问题：Provider 更新时，所有 Consumer 都会重渲染，即使它们只使用了 State 的一部分。

优化策略：读写分离

将 State (数据) 和 Dispatch (修改方法) 分离到两个不同的 Context 中。

// 优化后的 Context 结构
export const UserStateContext = createContext<State | null>(null);
export const UserDispatchContext = createContext<Dispatch<Action> | null>(null);

export const UserProvider = ({ children }) => {
  const [state, dispatch] = useReducer(reducer, initialState);

  return (
    <UserDispatchContext.Provider value={dispatch}>
      <UserStateContext.Provider value={state}>
        {children}
      </UserStateContext.Provider>
    </UserDispatchContext.Provider>
  );
};

// 收益：
// 只需要触发更新的组件（比如一个按钮）可以只 consume UserDispatchContext。
// 当 state 变化时，这个按钮组件 **不会** 重渲染，因为它不依赖 UserStateContext。

3.2 状态下放 (State Colocation)

在引入全局状态管理前，先问自己：这个状态真的需要全局吗？ 将状态尽可能的下放到离使用它最近的父组件，甚至是组件内部，是提升 React 应用性能最简单有效的方法。

四、 React 常见反模式 (Anti-Patterns)

4.1 在 useEffect 中计算衍生状态

❌ 错误示范：

const [firstName, setFirstName] = useState('John');
const [lastName, setLastName] = useState('Doe');
const [fullName, setFullName] = useState('');

// 多余的渲染 pass：render -> useEffect -> setState -> re-render
useEffect(() => {
  setFullName(`${firstName} ${lastName}`);
}, [firstName, lastName]);

✅ 正确示范：

// 直接在渲染过程中计算。React 极快，不要担心这点计算量。
const fullName = `${firstName} ${lastName}`; 

4.2 Prop Drilling (属性透传)

当看到 <Child user={user} /> -> <GrandChild user={user} /> -> <GreatGrandChild user={user} /> 时，你需要重构。

解法 1：Component Composition (组件组合) 将组件作为 children 或 props 传递，而不是传递数据。

// 改造前
<Page user={user} /> // Page 内部要把 user 一层层传下去

// 改造后
<Page>
  <Avatar user={user} /> {/* 直接在这里使用 user */}
</Page>

解法 2：Context 如果组件层级确实太深且无法组合，再考虑 Context，比如主题切换、用户信息等。

通过避免这些反模式，并结合前文提到的渲染策略与 Hooks 技巧，你已经掌握了构建高质量 React 应用的核心心法。

一、 HTTP/0.9 & 1.0：协议的诞生与雏形

1. HTTP/0.9 (1991年)

• 设计初衷：极简的数据传输协议。
• 特征：
  • 单行协议：请求只有一行，例如 GET /index.html。
  • 无 Header：没有请求头和响应头。
  • 仅限 HTML：服务器只能返回 HTML 格式的字符串。
  • 连接模型：短连接。每次请求都需要建立 TCP 连接，响应结束后立即断开。

2. HTTP/1.0 (1996年)

随着互联网的发展，仅传输文字已无法满足需求。

• 核心改进：
  • 引入 Header：允许传输元数据（Metadata）。
  • 状态码 (Status Code)：如 200, 404, 500，明确告知请求结果。
  • 多媒体支持 (Content-Type)：可以传输图片、音频、视频等二进制文件。
  • 基础缓存：引入 Expires 和 Last-Modified。
• 致命痛点：
  • 连接无法复用：依然沿用短连接模型。加载一个包含 10 张图片的网页，需要建立 11 次 TCP 连接（1 次 HTML + 10 次图片）。
  • 性能损耗：TCP 三次握手和慢启动（Slow Start）机制导致严重的延迟。

二、 HTTP/1.1：标准确立与性能优化 (1997年)

HTTP/1.1 是目前互联网上使用最广泛的协议版本，它主要解决了连接复用问题。

1. 核心特性

• 持久连接 (Keep-Alive)：
  • 引入 Connection: keep-alive（默认开启）。
  • 允许在一个 TCP 连接上发送多个 HTTP 请求，大幅减少了 TCP 握手的开销。
• 管道化 (Pipelining)：
  • 试图允许客户端同时发送多个请求，而无需等待响应。
  • 失败告终：由于服务器必须按顺序返回响应，且实现复杂，现代浏览器默认均未开启此功能。
• 高级缓存控制：
  • 引入 Cache-Control (如 max-age, no-cache)，提供了比 HTTP/1.0 更精准的缓存策略。
  • 引入 ETag (实体标签)，通过内容哈希校验资源是否变更，比时间戳更可靠。
• Host 头：
  • 强制要求请求包含 Host 头。这使得虚拟主机 (Virtual Hosting) 成为可能，即一台物理服务器可以托管多个域名。
• 丰富的方法 (Methods)：
  • 规范了 PUT, DELETE, OPTIONS, PATCH 等方法，为后来的 RESTful API 奠定了基础。
• 断点续传：
  • 引入 Range 头，允许请求资源的特定部分（如视频拖拽播放）。

2. 遗留痛点：HTTP 队头阻塞 (Head-of-Line Blocking)

虽然 Keep-Alive 复用了连接，但 HTTP/1.1 的请求处理依然是串行的。

• 现象：在一个 TCP 连接中，如果第一个请求处理很慢（例如数据库查询耗时 2秒），后续的请求（哪怕只是一个 1KB 的 CSS 文件）都必须排队等待。
• 临时方案：浏览器为了缓解这个问题，通常会针对同一个域名同时建立 6 个 TCP 连接（并发限制）。但这大大增加了服务器的资源消耗。

三、 HTTP/2：二进制分帧与多路复用 (2015年)

HTTP/2 是对 HTTP 传输层的彻底重构，旨在应用层解决性能瓶颈。

1. 二进制分帧 (Binary Framing)

• 改变：HTTP/1.x 是文本协议（可读性好，但解析低效），HTTP/2 是二进制协议。
• 机制：将传输信息分割为更小的帧 (Frame)，并进行二进制编码。

2. 多路复用 (Multiplexing) —— 最核心变革

• 机制：在单一 TCP 连接上，可以并行交错发送无数个请求和响应。
• 优势：彻底解决了 HTTP 1.1 的队头阻塞问题。
• 效果：浏览器不再需要建立 6 个连接，通常一个域名只需要一个 TCP 连接。

3. 头部压缩 (HPACK)

• 背景：HTTP 请求头通常包含大量重复信息（如 Cookie, User-Agent），且每次请求都要重复发送，浪费带宽。
• 机制：客户端和服务器共同维护静态字典和动态字典，使用索引号代替重复的 Header 字段，大幅减少传输体积。

4. 服务端推送 (Server Push)

• 机制：服务器可以预测客户端需要的资源（如请求 index.html 时主动推送 style.css）。
• 现状：由于缓存一致性难以处理，该特性在实践中并未广泛流行，Chrome 已计划移除，推荐使用 103 Early Hints。

5. 新的痛点：TCP 队头阻塞

HTTP/2 虽然解决了应用层的队头阻塞，但将所有数据都压在一个 TCP 连接上，导致了TCP 层面的队头阻塞。

• 现象：TCP 保证数据按序到达。一旦发生丢包，操作系统内核会暂停将后续数据包交付给应用层，直到丢失的包重传成功。
• 结果：在弱网环境下（高丢包率），HTTP/2 的性能表现可能反而不如 HTTP/1.1（因为 HTTP/1.1 有多个连接，一个断了不影响其他）。

四、 HTTP/3：基于 UDP 的革新 (2022年 RFC 标准化)

为了解决 TCP 的固有缺陷，HTTP/3 抛弃了 TCP，改用基于 UDP 的 QUIC 协议。

1. QUIC 协议 (Quick UDP Internet Connections)

HTTP/3 将传输层从 TCP 换成了 UDP，并在应用层（用户态）实现了可靠传输机制。

2. 真正的独立流 (Independent Streams)

• 机制：每个流（Stream）在逻辑上是独立的。
• 优势：彻底解决 TCP 队头阻塞。如果 Stream A 的数据包丢失，只会阻塞 Stream A，Stream B 和 C 依然可以正常传输。

3. 0-RTT 极速握手

• 机制：QUIC 将传输握手和 TLS 加密握手合并。
• 效果：
  • 首次连接：1 RTT。
  • 再次连接：0 RTT（直接发送加密数据）。

4. 连接迁移 (Connection Migration)

• 背景：TCP 连接由四元组（源IP、源端口、目标IP、目标端口）标识。切换网络（如 Wi-Fi 切 4G）会导致 IP 变化，连接断开。
• 机制：QUIC 使用 Connection ID (CID) 标识连接。
• 优势：只要 CID 不变，即使用户 IP 发生变化，连接依然保持，无需重连。这对移动端应用极其重要。

五、 实战指南：Go 语言实现 (Gin / Echo)

在 Go 语言中，启用 HTTP/2 非常简单，因为标准库 net/http 原生支持。启用 HTTP/3 则需要引入 quic-go。

1. Gin 框架 (HTTP/2)

只要开启 TLS (HTTPS)，Go 会自动协商升级到 HTTP/2。

package main

import (
    "log"
    "github.com/gin-gonic/gin"
)

func main() {
    r := gin.Default()

    r.GET("/ping", func(c *gin.Context) {
        // c.Request.Proto 将显示 "HTTP/2.0"
        c.String(200, "Protocol: "+c.Request.Proto)
    })

    // HTTP/2 强制要求 HTTPS
    // 使用 mkcert localhost 生成本地测试证书
    log.Println("Gin running on https://localhost:8443")
    if err := r.RunTLS(":8443", "server.crt", "server.key"); err != nil {
        log.Fatal(err)
    }
}

2. Echo 框架 (HTTP/2)

同理，使用 StartTLS 即可。

package main

import (
    "net/http"
    "github.com/labstack/echo/v4"
)

func main() {
    e := echo.New()
    e.GET("/", func(c echo.Context) error {
        return c.String(http.StatusOK, "Protocol: "+c.Request().Proto)
    })
    e.Logger.Fatal(e.StartTLS(":8443", "server.crt", "server.key"))
}

3. 启用 HTTP/3 (QUIC)

需要使用 github.com/quic-go/quic-go/http3 包。

package main

import (
    "log"
    "net/http"
    "github.com/gin-gonic/gin"
    "github.com/quic-go/quic-go/http3"
)

func main() {
    r := gin.Default()
    r.GET("/", func(c *gin.Context) {
        // 关键：添加 Alt-Svc 头，告知浏览器该服务支持 HTTP/3
        c.Header("Alt-Svc", `h3=":443"; ma=2592000`)
        c.String(200, "Hello via "+c.Request.Proto)
    })

    // 启动 HTTP/3 服务器 (监听 UDP)
    go func() {
        server := http3.Server{
            Addr:    ":443",
            Handler: r,
        }
        log.Println("HTTP/3 server listening on :443")
        err := server.ListenAndServeTLS("server.crt", "server.key")
        if err != nil {
            log.Fatal(err)
        }
    }()

    // 同时启动 HTTP/1.1 & HTTP/2 (监听 TCP) 作为兼容降级
    log.Println("HTTP/1.1 & HTTP/2 server listening on :443")
    err := http.ListenAndServeTLS(":443", "server.crt", "server.key", r)
    if err != nil {
        log.Fatal(err)
    }
}

六、 协议选型建议

总结：对于绝大多数公网 Web 应用，HTTP/2 + HTTPS 是标准配置。如果你专注于移动端体验优化，应该开始尝试 HTTP/3。

1. 为什么我们需要 WebSocket？

1.1 HTTP 的局限性

在 WebSocket 出现之前，为了实现“实时”效果，开发者们通常采用以下几种技术：

• 轮询 (Polling)：客户端每隔一段时间（如 1 秒）向服务器发送 HTTP 请求询问是否有新数据。
  • 缺点：浪费带宽和服务器资源，大部分请求可能是空的。
• 长轮询 (Long Polling)：客户端发起请求，服务端挂起请求直到有数据才返回。
  • 缺点：虽然减少了无效请求，但依然存在 HTTP 头部开销大、连接频繁建立释放的问题。此外，服务端需要长时间维持大量挂起的连接，在高并发场景下会严重消耗服务器资源（如线程、文件描述符），处理不当极易引发资源泄露。

无论采用哪种轮询方式，核心痛点在于 HTTP 协议的被动性。请求必须由客户端发起，服务端无法主动推送。这种同步的“请求-响应”机制导致客户端为了获取最新状态，不得不进行频繁的无效询问或长时间的等待，这在实时性要求高的场景下显得极不合理。 HTTP 协议本质上是半双工、无状态、请求-响应模式的。服务器无法主动向客户端推送数据。

1.2 WebSocket 的核心优势

WebSocket 是一种在单个 TCP 连接上进行全双工 (Full Duplex) 通信的协议。

• 全双工：客户端和服务器都可以随时向对方发送数据，不再受限于“请求-响应”模式。
• 低开销：建立连接后，数据传输时不再需要携带臃肿的 HTTP 头部，只需要极少的帧头（Frame Header）。
• 低延迟：无需频繁建立连接，数据传输实时性更高。

2. WebSocket 协议深度解析

WebSocket 协议 (RFC 6455) 建立在 TCP 之上，它复用了 HTTP 的握手通道，但随后升级为独立的 WebSocket 协议。

2.1 握手流程 (Handshake)

连接的建立始于一个标准的 HTTP GET 请求，但带有一些特殊的 Header：

客户端请求：

GET /chat HTTP/1.1
Host: server.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13

• Connection: Upgrade 和 Upgrade: websocket：告诉服务器我想升级协议。
• Sec-WebSocket-Key：一个随机的 Base64 字符串，用于验证服务器是否支持 WebSocket。

服务端响应：

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

• 101 Switching Protocols：表示服务器同意升级。
• Sec-WebSocket-Accept：服务器通过 Sec-WebSocket-Key 拼接固定的 GUID (258EAFA5-E914-47DA-95CA-C5AB0DC85B11) 后进行 SHA-1 摘要并 Base64 编码得出。客户端校验此值以确认连接成功。

2.2 数据帧 (Data Frame)

握手完成后，双方通过数据帧传输数据。WebSocket 的帧结构设计得非常紧凑：

      0                   1                   2                   3
      0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
     +-+-+-+-+-------+-+-------------+-------------------------------+
     |F|R|R|R| opcode|M| Payload len |    Extended payload length    |
     |I|S|S|S|  (4)  |A|     (7)     |             (16/64)           |
     |N|V|V|V|       |S|             |   (if payload len==126/127)   |
     | |1|2|3|       |K|             |                               |
     +-+-+-+-+-------+-+-------------+ - - - - - - - - - - - - - - - +
     |     Extended payload length continued, if payload len == 127  |
     + - - - - - - - - - - - - - - - +-------------------------------+
     |                               |Masking-key, if MASK set to 1  |
     +-------------------------------+-------------------------------+
     | Masking-key (continued)       |          Payload Data         |
     +-------------------------------- - - - - - - - - - - - - - - - +
     :                     Payload Data continued ...                :
     + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
     |                     Payload Data continued ...                |
     +---------------------------------------------------------------+

• FIN (1 bit)：结束标志位 (Finish)。
  • 如果为 1，表示这是消息的最后一个分片（Fragment）。
  • 如果为 0，表示还有后续分片。这允许发送端在不知道完整消息长度的情况下就开始传输（流式传输）。
• RSV1, RSV2, RSV3 (1 bit each)：保留位 (Reserved)。
  • 必须设置为 0，除非协商了扩展（Extension）定义了它们的含义。
  • 例如：在使用 permessage-deflate 扩展进行压缩时，RSV1 可能会被置为 1。
• Opcode (4 bits)：操作码，定义有效负载的数据类型。
  • 0x0: 延续帧 (Continuation Frame)。用于分片传输，表示该帧内容应追加到上一帧之后。
  • 0x1: 文本帧 (Text Frame)。UTF-8 编码的文本。
  • 0x2: 二进制帧 (Binary Frame)。任意二进制数据。
  • 0x3 - 0x7: 保留用于未来的非控制帧。
  • 0x8: 连接关闭 (Connection Close)。
  • 0x9: Ping。心跳请求。
  • 0xA: Pong。心跳响应。
  • 0xB - 0xF: 保留用于未来的控制帧。
• Mask (1 bit)：掩码标志位。
  • 定义“有效负载数据”是否添加了掩码。
  • 规则：客户端发送给服务端的帧必须设置为 1；服务端发送给客户端的帧必须设置为 0。
  • 目的：防止代理服务器缓存中毒攻击（Proxy Cache Poisoning）。
• Payload Length (7 bits)：有效负载长度。
  • 0-125：实际数据长度。
  • 126：实际长度由随后的 16 位（Extended payload length）表示。
  • 127：实际长度由随后的 64 位（Extended payload length）表示。
• Masking-Key (0 or 4 bytes)：掩码密钥。
  • 仅当 Mask 位为 1 时存在。
  • 这是一个 32 位的随机数，用于对负载数据进行异或（XOR）解密。
• Payload Data：应用数据。
  • 实际传输的业务数据（如果是文本帧，则是 UTF-8 文本；如果是控制帧，可能包含状态码等）。

3. 客户端实战：TypeScript

我们将使用原生 WebSocket API 并结合 TypeScript 封装一个具有自动重连、心跳检测功能的客户端类。

3.1 核心代码实现

// ws-client.ts

type MessageHandler = (data: any) => void;

interface WSOptions {
    url: string;
    reconnectInterval?: number; // 重连间隔
    heartbeatInterval?: number; // 心跳间隔
}

export class WSClient {
    private ws: WebSocket | null = null;
    private options: WSOptions;
    private shouldReconnect = true;
    private messageHandlers: Set<MessageHandler> = new Set();
    private heartbeatTimer: number | null = null;

    constructor(options: WSOptions) {
        this.options = {
            reconnectInterval: 3000,
            heartbeatInterval: 30000,
            ...options,
        };
    }

    // 初始化连接
    public connect() {
        try {
            this.ws = new WebSocket(this.options.url);
            this.bindEvents();
        } catch (e) {
            console.error('WebSocket connection failed:', e);
            this.reconnect();
        }
    }

    private bindEvents() {
        if (!this.ws) return;

        this.ws.onopen = () => {
            console.log('WebSocket Connected');
            this.startHeartbeat();
        };

        this.ws.onmessage = (event) => {
            try {
                // 假设服务端也返回 JSON 格式
                const data = JSON.parse(event.data);
                
                // 处理心跳响应（Pong）
                if (data.type === 'pong') {
                    console.log('Received Pong');
                    return;
                }

                this.messageHandlers.forEach(handler => handler(data));
            } catch (e) {
                console.warn('Non-JSON message received:', event.data);
            }
        };

        this.ws.onclose = (event) => {
            console.log('WebSocket Closed:', event.code, event.reason);
            this.stopHeartbeat();
            this.reconnect();
        };

        this.ws.onerror = (error) => {
            console.error('WebSocket Error:', error);
            // onerror 通常紧接着 onclose，重连逻辑在 onclose 处理
        };
    }

    // 发送消息
    public send(data: any) {
        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
            this.ws.send(JSON.stringify(data));
        } else {
            console.error('WebSocket is not connected');
        }
    }

    // 注册消息监听
    public onMessage(handler: MessageHandler) {
        this.messageHandlers.add(handler);
        return () => this.messageHandlers.delete(handler); // 返回取消订阅函数
    }

    // 自动重连机制
    private reconnect() {
        if (!this.shouldReconnect) return;
        
        console.log(`Attempting to reconnect in ${this.options.reconnectInterval}ms...`);
        setTimeout(() => {
            this.connect();
        }, this.options.reconnectInterval);
    }

    // 心跳检测
    private startHeartbeat() {
        this.stopHeartbeat();
        this.heartbeatTimer = window.setInterval(() => {
            this.send({ type: 'ping' });
        }, this.options.heartbeatInterval);
    }

    private stopHeartbeat() {
        if (this.heartbeatTimer) {
            clearInterval(this.heartbeatTimer);
            this.heartbeatTimer = null;
        }
    }

    // 手动关闭
    public close() {
        this.shouldReconnect = false;
        this.stopHeartbeat();
        this.ws?.close();
    }
}

4. 服务端实战

我们将分别展示 Go 和 Node.js (TypeScript) 的服务端实现，两者都将实现基本的消息回显（Echo）和广播功能。

4.1 Go 语言实现

Go 语言处理 WebSocket 非常高效。我们将使用官方推荐的第三方库 github.com/gorilla/websocket。

// main.go
package main

import (
    "log"
    "net/http"
    "sync"

    "github.com/gorilla/websocket"
)

// 升级器配置
var upgrader = websocket.Upgrader{
    CheckOrigin: func(r *http.Request) bool {
        return true; // 允许所有跨域请求，生产环境需严格配置
    },
}

// 简单的客户端管理器
type ClientManager struct {
    clients    map[*websocket.Conn]bool
    broadcast  chan []byte
    register   chan *websocket.Conn
    unregister chan *websocket.Conn
    mutex      sync.Mutex
}

func (manager *ClientManager) start() {
    for {
        select {
        case conn := <-manager.register:
            manager.mutex.Lock()
            manager.clients[conn] = true
            manager.mutex.Unlock()
            log.Println("New client connected")
        case conn := <-manager.unregister:
            manager.mutex.Lock()
            if _, ok := manager.clients[conn]; ok {
                delete(manager.clients, conn)
                conn.Close()
                log.Println("Client disconnected")
            }
            manager.mutex.Unlock()
        case message := <-manager.broadcast:
            manager.mutex.Lock()
            for conn := range manager.clients {
                err := conn.WriteMessage(websocket.TextMessage, message)
                if err != nil {
                    log.Printf("Write error: %v", err)
                    conn.Close()
                    delete(manager.clients, conn)
                }
            }
            manager.mutex.Unlock()
        }
    }
}

var manager = ClientManager{
    broadcast:  make(chan []byte),
    register:   make(chan *websocket.Conn),
    unregister: make(chan *websocket.Conn),
    clients:    make(map[*websocket.Conn]bool),
}

func handleConnections(w http.ResponseWriter, r *http.Request) {
    // 1. 升级 HTTP 为 WebSocket
    ws, err := upgrader.Upgrade(w, r, nil)
    if err != nil {
        log.Fatal(err)
    }
    
    // 2. 注册客户端
    manager.register <- ws

    // 3. 循环读取消息
    defer func() {
        manager.unregister <- ws
    }()

    for {
        _, msg, err := ws.ReadMessage()
        if err != nil {
            break
        }
        log.Printf("Received: %s", msg)
        
        // 简单处理：将收到的消息广播给所有人
        manager.broadcast <- msg
    }
}

func main() {
    go manager.start()
    http.HandleFunc("/ws", handleConnections)
    log.Println("Server started on :8080")
    err := http.ListenAndServe(":8080", nil)
    if err != nil {
        log.Fatal("ListenAndServe: ", err)
    }
}

4.2 TypeScript (Node.js) 实现

Node.js 中最常用的库是 ws。

// server.ts
import { WebSocketServer, WebSocket } from 'ws';
import http from 'http';

const server = http.createServer();
const wss = new WebSocketServer({ server });

wss.on('connection', (ws: WebSocket) => {
    console.log('New client connected');

    ws.on('message', (message: Buffer) => {
        const msgStr = message.toString();
        console.log('Received:', msgStr);

        // 处理 Ping/Pong（如果客户端发 JSON 格式的心跳）
        try {
            const data = JSON.parse(msgStr);
            if (data.type === 'ping') {
                ws.send(JSON.stringify({ type: 'pong' }));
                return;
            }
        } catch (e) {
            // 非 JSON 消息，继续处理
        }

        // 广播消息给所有客户端
        wss.clients.forEach((client) => {
            if (client.readyState === WebSocket.OPEN) {
                client.send(msgStr); // 原样转发
            }
        });
    });

    ws.on('close', () => {
        console.log('Client disconnected');
    });

    ws.on('error', (err) => {
        console.error('Socket error:', err);
    });
});

server.listen(8081, () => {
    console.log('Node.js WebSocket Server started on :8081');
});

5. 进阶实践：打造健壮的连接

5.1 心跳检测 (Heartbeat)

网络连接可能因为各种原因（NAT 超时、网络波动）中断，但双方并未感知到（TCP 半开连接）。

• 机制：客户端定时发送 Ping 消息，服务端回复 Pong。
• 策略：如果客户端在一定时间内未收到 Pong，或服务端在一定时间内未收到任何消息，则主动断开连接并触发重连。

5.2 断线重连

在客户端实现指数退避 (Exponential Backoff) 算法，避免网络恢复瞬间大量客户端同时重连冲击服务器。

• 例如：第 1 次失败等待 1s，第 2 次 2s，第 3 次 4s... 直到达到最大上限。

5.3 弱网优化策略

在移动端或网络不稳定的环境下，仅仅依靠重连和心跳是不够的。我们需要更主动的策略来提升用户体验：

1. 消息队列与 ACK 机制

   • 问题：断线期间产生的消息会丢失；重连后消息顺序可能错乱。
   • 方案：客户端维护一个发送队列。每条消息带上唯一 ID (msg_id)。发送后不立即删除，只有收到服务端回复的 ACK 确认包后才从队列移除。重连成功后，自动重发队列中未确认的消息。

2. 网络状态监听

   • 利用 HTML5 的 navigator.onLine 属性和 window.addEventListener('online') / offline 事件。
   • 一旦监听到 offline，立即暂停心跳和消息发送，将 UI 切换为“连接中...”状态；监听到 online，立即触发一次重连尝试。

3. 数据压缩

   • 对于数据量较大的应用，开启 WebSocket 的协议扩展 permessage-deflate。
   • 虽然会增加 CPU 开销，但能显著减少传输数据量，在弱网下能有效提高传输成功率。

4. 智能降级

   • 如果 WebSocket 连接连续失败多次（如公司防火墙屏蔽），应自动降级为 HTTP 长轮询 (Long Polling) 模式，确保核心业务可用。

6. WebSocket 鉴权实践

WebSocket 的鉴权是一个常见的痛点，因为浏览器原生的 WebSocket API 不支持设置自定义 HTTP Header（例如 Authorization: Bearer <token>）。

6.1 主流方案：Query 参数携带 Token

这是目前最通用、兼容性最好的方案。

• 原理：在建立连接的 URL 中携带 Token。
• 流程：
  1. 客户端登录，获取 Token。
  2. 发起连接：new WebSocket('wss://api.example.com/ws?token=eyJhbGciOi...')
  3. 服务端在 Upgrade 握手阶段，解析 URL Query 参数，验证 Token。
  4. 验证通过 -> 允许升级 (HTTP 101)；验证失败 -> 拒绝连接 (HTTP 401)。

优点：

• 实现简单，兼容所有客户端。
• 在连接建立之初就拦截非法请求，节省服务器资源。

缺点：

• Token 可能会暴露在服务器日志或浏览器历史记录中（建议使用一次性 Ticket 或短期 Token 缓解）。

代码实现 (Node.js 示例)

// 基于 ws 库的鉴权
import { WebSocketServer } from 'ws';
import http from 'http';
import { URL } from 'url';

const server = http.createServer();
const wss = new WebSocketServer({ noServer: true }); // 开启 noServer 模式，手动处理升级

// 模拟 Token 验证函数
function verifyToken(token: string): boolean {
    return token === 'valid-secret-token';
}

server.on('upgrade', (request, socket, head) => {
    const url = new URL(request.url || '', `http://${request.headers.host}`);
    const token = url.searchParams.get('token');

    if (!token || !verifyToken(token)) {
        socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
        socket.destroy();
        return;
    }

    // 鉴权通过，完成升级
    wss.handleUpgrade(request, socket, head, (ws) => {
        wss.emit('connection', ws, request);
    });
});

wss.on('connection', (ws) => {
    console.log('Authenticated client connected!');
    ws.send('Welcome, authorized user!');
});

server.listen(8082);

6.2 其他鉴权方案简述

1. 连接后第一时间认证

   • 原理：先建立普通的 WebSocket 连接，连接成功后的第一条消息必须是包含 Token 的认证消息。
   • 优点：灵活，Token 不会暴露在 URL 中。
   • 缺点：服务端需要维护“未认证”状态的连接，如果攻击者建立大量连接但不发送认证包，会消耗服务器资源（需配合超时断开机制）。

2. Cookie 鉴权

   • 原理：WebSocket 握手请求会自动携带同域下的 Cookie。
   • 优点：利用浏览器原生机制，无需额外代码。
   • 缺点：无法跨域（或跨域配置复杂），不适用于非浏览器客户端（如移动端 App 需手动管理 Cookie），易受 CSRF 攻击。

3. Ticket 机制 (推荐用于高安全场景)

   • 原理：
     1. 客户端先向 HTTP 接口 POST Token，服务端校验通过后生成一个临时的、一次性的短 Ticket。
     2. 客户端使用 Ticket 建立 WebSocket 连接：ws://...?ticket=xxx。
     3. 服务端验证 Ticket 有效性并立即销毁。
   • 优点：Token 不泄露，URL 中的 Ticket 即使泄露也已失效。

7. 生产环境部署指南

在本地开发完成后，将 WebSocket 服务部署到生产环境时，有两个关键点必须注意：反向代理配置和SSL/TLS 加密。

7.1 Nginx 反向代理配置

大多数 Web 服务都会使用 Nginx 作为网关。默认情况下，Nginx 不会转发 Upgrade 和 Connection 头部，导致 WebSocket 握手失败（通常报 400 或 426 错误）。

你需要显式添加以下配置：

# nginx.conf
location /ws {
    proxy_pass http://backend_server_pool;
    proxy_http_version 1.1; # WebSocket 必须使用 HTTP/1.1
    
    # 核心配置：转发 Upgrade 和 Connection 头
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    
    # 其他常用配置
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_read_timeout 600s; # 延长超时时间，避免 Nginx 主动断开长连接
}

7.2 必须使用 WSS (SSL/TLS)

在生产环境中，强烈建议（甚至强制）使用 wss:// 协议，而不是 ws://。

1. 安全性：防止数据被中间人窃听或篡改（WebSocket 握手包含敏感的 Auth Token）。
2. 穿透性：这是更实际的原因。许多公司的防火墙或代理服务器不认识 WebSocket 协议，可能会直接阻断非加密的 ws:// 连接。而 wss:// 基于 TLS 加密，在中间设备看来就是普通的 HTTPS 流量，能有效规避拦截，提高连接成功率。

8. 各语言主流 WebSocket 库推荐

在真实的企业级开发中，我们通常不会从零手写 WebSocket 协议解析，而是站在巨人的肩膀上。以下是各主流语言经过大规模生产环境验证的“杀手级”库：

8.1 TypeScript / Node.js

• ws
  • 特点：极度轻量、快速，最接近原生协议。
  • 场景：追求极致性能，或者你需要自己封装上层逻辑（如心跳、鉴权）。
• Socket.IO
  • 特点：不仅仅是 WebSocket。它自带了一套协议，支持自动降级（WebSocket 不可用时切回长轮询）、自动重连、房间（Rooms）、广播（Broadcast）。
  • 场景：快速构建复杂的实时应用（聊天室、游戏），需要兼容老旧浏览器或复杂网络环境。注意：客户端也必须使用 Socket.IO Client，不能用原生 WebSocket 连接。

8.2 Go

• gorilla/websocket
  • 特点：Go 社区的事实标准，文档详尽，API 稳定。
  • 场景：绝大多数标准业务场景。
• gobwas/ws
  • 特点：零内存分配（Zero-copy upgrade），追求极致性能。
  • 场景：你需要编写能够处理百万级连接的高性能网关（Gateway）。

8.3 Java

• Spring Boot WebSocket
  • 特点：企业级开发首选，与 Spring 生态（Security, MVC）无缝集成。支持 STOMP 协议（一种消息子协议）。
  • 场景：传统的企业级后端服务，CRUD 业务系统。
• Netty
  • 特点：异步事件驱动的网络框架，性能怪兽。
  • 场景：高性能游戏服务端、即时通讯（IM）底层设施。

8.4 Python

• websockets
  • 特点：基于 Python asyncio 构建，现代、优雅、性能好。
  • 场景：基于 FastAPI 或 Aiohttp 的异步微服务。
• Django Channels
  • 特点：将 WebSocket 引入 Django，保持了 Django 的开发体验。
  • 场景：基于 Django 的全栈 Web 应用。

9. 总结

WebSocket 是构建实时应用的首选技术。通过本文，我们了解了：

1. 它解决了 HTTP 轮询的低效问题。
2. 客户端需要处理好心跳保活和断线重连。
3. 服务端（Go/Node.js）的核心是管理连接池和广播消息。
4. 鉴权推荐使用 Query 参数携带 Token 或 Ticket 机制。
5. 上线时务必配置好 Nginx 并开启 WSS。
6. 善用成熟的开源库（如 ws, gorilla, netty 等）来避免重复造轮子。

10. 参考文献

1. RFC 6455 - The WebSocket Protocol
2. MDN Web Docs - WebSocket API
3. WebSocket｜概念、原理、用法及实践

1. 回顾过去：Go 1.23 以前的拉链法

1.1 核心结构

• hmap：Map 的头节点，保存了 count、B、buckets 指针等。
• bmap (Bucket)：每个桶固定存储 8 个键值对。为了内存对齐，它将 8 个 tophash 放在一起，接着是 8 个 key，最后是 8 个 value。
• overflow：当桶满时，通过 overflow 指针挂载一个新的 bmap。

1.2 冲突与扩容

• 哈希冲突：使用拉链法。冲突的 Key 会被放入溢出桶中。
• 扩容因子：固定为 6.5。
• 扩容方式：当负载因子超过 6.5 或溢出桶过多时，触发双倍扩容或等量扩容，采用渐进式搬迁。

2. 硬核对比：拉链法 vs 开放寻址法

3. 核心数据结构：从 Bucket 到 Group

Go 1.24 弃用了 bmap，引入了 Group 和 Metadata 的概念。

3.1 hmap：新的元数据头

Map 的头部结构体依然叫 hmap，但内部字段发生了变化：

type hmap struct {
    count     int    // 元素总数
    flags     uint8  // 状态位（写入中、迭代中等）
    B         uint8  // 指数级大小，2^B 表示 Group 的对数
    hash0     uint32 // 哈希种子，对抗哈希攻击的关键

    // 核心存储指针
    table     unsafe.Pointer // 指向当前的存储表（包含元数据数组和数据数组）
    oldtable  unsafe.Pointer // 扩容时的旧表指针，用于增量搬迁
    
    // ... 
}

3.2 控制字节（Control Byte）与指纹（Fingerprint）

这是 Swiss Table 的精髓。每个插槽不再只靠 tophash 过滤，而是使用 1 个字节（8 位）的控制位：

• 0b10000000 (0x80)：Empty。表示此槽位完全为空。
• 0b11111110 (0xfe)：Deleted（墓碑标记）。表示元素已删，但探测链不能断。
• 0b0xxxxxxx (h2)：Occupied。最高位为 0，后 7 位存储哈希值的低 7 位，称为 h2 指纹。

4. 性能杀手锏：SIMD 并行匹配

在查找一个 Key 时，Go 1.24 的逻辑如下：

1. 哈希拆分：将 64 位哈希值拆为 h1（高 57 位）和 h2（低 7 位）。
2. 定位 Group：通过 h1 找到对应的 Group。
3. 向量化查找：
   • 现代 CPU（如 amd64 上的 SSE2/AVX）支持 SIMD 指令。
   • 运行时会一次性加载 Group 内 8 个插槽的元数据（共 8 字节）。
   • 使用一条指令（类似于 PCMPEQB）将这 8 个字节与目标的 h2 指纹进行比较，瞬间得到一个掩码。
4. 精确校验：如果掩码指示有匹配项，再去内存里取 Key 进行 equal 比较。

为什么快？ 因为它把原本需要 8 次循环的比较，压缩成了一次指令和一次位运算，且元数据与数据在内存布局上高度紧凑。

5. 冲突解决：三角形探测（Triangular Probing）

由于不再有溢出桶，当某个 Group 满员且指纹不匹配时，Go 1.24 使用一种特殊的二次探测——三角形探测（Triangular Probing）来寻找下一个 Group：

• 探测公式：p(i) = (h1 + i*(i+1)/2) mod 2^B
• 为什么不是线性探测？ 线性探测容易产生“一级聚集”（Primary Clustering），即大量数据挤在一起，导致探测链越来越长。
• 为什么不是通用平方探测？ 通用的平方探测（如 $ai^2 + bi + c$）计算相对复杂。而三角形探测在表大小为 $2^k$ 时，已被数学证明能遍历到表中所有的槽位，且计算只需简单的算术运算。
• 为什么不使用多次哈希（Double Hashing）？ 多次哈希在每次冲突时都需要重新计算哈希值，CPU 指令开销过大。在 Swiss Table 这种对性能极其敏感的场景下，增加哈希计算次数会直接抵消掉开放寻址带来的缓存红利。
• 三角形探测的优势：它的步长随探测次数增加，能有效缓解聚集效应，同时保持了极高的计算效率。

• 墓碑标记（Tombstone）：在删除元素时，槽位会被标记为 Deleted (0xfe)。这是为了告诉查找流程：“这里虽然没数据，但探测链在此并未中断，请继续往后找”。只有遇到真正的 Empty (0x80) 才会停止探测。

  ---

6. 扩容：更激进，也更高效

6.1 负载因子（Load Factor）的飞跃

• 旧版：负载因子约为 6.5/8。
• Go 1.24+：由于 Swiss Table 的高效过滤，负载因子提升到了 ~87.5% (7/8)。
• 结果：在同样的内存开销下，1.24 版能多装约 7% 的数据，且在高负载下的性能劣化远小于旧版。

6.2 搬迁逻辑

扩容依然是渐进式（Incremental）的。当触发扩容（负载因子超标或探测链过长）时：

1. 分配一个 2 倍大小的新表。
2. 每次进行 mapassign 或 mapdelete 操作时，搬迁旧表中的 Group 到新表。
3. 这种设计保证了扩容过程不会造成突发的长尾延迟（P99 延迟）。

7. 开发者需要注意什么？

1. 内存占用更低：在海量 Map 场景下，升级到 1.24 后通常能观察到 5%~10% 的 RSS 内存下降。
2. 迭代随机性：虽然底层重写，但 map 的迭代顺序依然是伪随机的，不要依赖它。
3. 性能红利：这是一个“透明”的优化，升级工具链即可享受，无需修改任何代码。

总结

Go 1.24 的 Map 重构是工程领域“榨干硬件性能”的典范。它通过 Swiss Table 将算法（开放寻址）与硬件（SIMD、Cache Line）深度绑定。对于开发者而言，这不仅意味着更快的执行速度，更标志着 Go 语言在追求极致性能的道路上又迈出了坚实的一步。

参考资料：

• Go Map的实现原理
• Faster Go maps with Swiss Tables - Go Blog

安装项目依赖

python -m venv .venv
source .venv/bin/activate
pip install patchright
pip install playwright_captcha
# 或使用 uv 安装
# uv init demo
# uv install playwright_captcha
# uv install patchright


#安装浏览器，当然你也可以不用安装 playwright 的浏览器，也可以使用系统自带的浏览器，通过 CDP 协议连接
# (.venv) D:\Dev\Blog-demo\playwright>patchright install -h
# Usage: playwright install [options] [browser...]

# ensure browsers necessary for this version of Playwright are installed

# Options:
#   --with-deps   install system dependencies for browsers
#   --dry-run     do not execute installation, only print information
#   --list        prints list of browsers from all playwright installations
#   --force       force reinstall of stable browser channels
#   --only-shell  only install headless shell when installing chromium
#   --no-shell    do not install chromium headless shell
#   -h, --help    display help for command


# Examples:
#   - $ install
#     Install default browsers.

#   - $ install chrome firefox
#     Install custom browsers, supports chromium, chromium-headless-shell, chromium-tip-of-tree-headless-shell, chrome, chrome-beta, msedge, msedge-beta, msedge-dev, bidi-chromium, firefox, webkit, webkit-wsl.

# 选择安装单个浏览器即可
patchright install chromium

唤起浏览器代码

from pathlib import Path
from patchright.async_api import BrowserContext, async_playwright, Page
from typing import Union
from playwright_captcha import ClickSolver, CaptchaType, FrameworkType


class Browser:
    def __init__(self):
        self._context: Union[BrowserContext, None] = None

    @property
    def context(self) -> BrowserContext:
        if self._context is None:
            raise RuntimeError("Browser context is not initialized.")  
        return self._context

    async def start(self, user_data_dir: Path | str = Path.home() / ".my_browser_data"):
        try:
            pw = await async_playwright().start()
            # Simulate starting the browser and creating a context
            self._context = await pw.chromium.launch_persistent_context(
                user_data_dir=user_data_dir,  # 用户数据目录，用于持久化保存 Cookie、缓存等浏览器状态
                headless=False,  # 是否以无头模式运行（无界面）。注：某些防爬机制下，headless 模式更易被检测
                chromium_sandbox=False,  # 是否启用 Chromium 沙箱，禁用它可以减少在某些环境（如 Docker）下的运行限制
                ignore_default_args=["--enable-automation"],  # 忽略默认的自动化标志，防止网站检测到正在使用自动化工具
                viewport={"width": 1920, "height": 1080},  # 设置浏览器视口的宽度和高度
                has_touch=False,  # 是否模拟支持触摸事件
                is_mobile=False,  # 是否模拟移动设备模式
                handle_sighup=False,  # 是否在接收到 SIGHUP 信号时关闭浏览器
                handle_sigterm=False,  # 是否在接收到 SIGTERM 信号时关闭浏览器
                handle_sigint=False,  # 是否在接收到 SIGINT 信号（如 Ctrl+C）时关闭浏览器
                timezone_id="Asia/Shanghai",  # 设置浏览器的时区
            )
        except Exception as e:
            raise e

    async def stop(self):
        if self._context:
            await self._context.close()
            self._context = None

    @classmethod
    async def handle_patch(cls, page: Page):
        solver = ClickSolver(
            framework=FrameworkType.PLAYWRIGHT,
            page=page,
            max_attempts=5,
            attempt_delay=8,
        )

        try:
            await solver.prepare()
            return solver
        except Exception as e:
            raise e

    @classmethod
    async def handle_turnstile(cls, page: Page, solver: ClickSolver):
        try:
            await solver.solve_captcha(
                captcha_container=page, captcha_type=CaptchaType.CLOUDFLARE_TURNSTILE
            )
        except Exception as e:
            ... # 如果没有检测到验证码，则跳过  

CDP 模式链接：

 async def launch_by_cdp(self, cdp_endpoint: str = "http://127.0.0.1:9222"):
        """
        需要事先启动浏览器，命令行示例：
        MacOS:
            /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir="/path/to/your/custom/profile"
        Windows:
            C:\\Program\ Files\\Google\\Chrome\\Application\\chrome.exe --remote-debugging-port=9222 --user-data-dir="C:\path\to\your\custom\profile"
        Linux:
            /usr/bin/google-chrome-stable --remote-debugging-port=9222 --user-data-dir="/path/to/your/custom/profile"
        Args:
            cdp_endpoint (_type_, optional): _description_. Defaults to "http://127.0.0.1:9222".

        Raises:
            e:   _description_
        """
        try:
            pw = await async_playwright().start()
            browser = await pw.chromium.connect_over_cdp(cdp_endpoint)
            self._context = browser.contexts[0]  # 假设只使用第一个上下文
        except Exception as e:
            raise e

使用

import asyncio
from browser import Browser


async def main():
    b = None
    try:
        b = Browser()
        await b.start("./chrome_data")
        page = await b.context.new_page()

        # 关键
        solver = await Browser.handle_patch(page)
        await page.goto("https://www.example.com", wait_until="load")
        await asyncio.sleep(2)  # 等待页面加载完成
        await Browser.handle_turnstile(page, solver) # 处理处理验证码
    except Exception as e:
        print(e)
    finally:
        if b is not None:
            await b.stop()

if __name__ == "__main__":
    asyncio.run(main())

如何捕获 Metamask 弹窗和 Google 弹窗等？

我们在自动化测试或者需要与 Google 扩展交互时，通过老办法的方式就是直接打开chrome-extension://nkbihfbeogaeaoehlefnkodbefgpgknn/home.html#unlock页面，但是这种不太用好，因为有时弹窗的界面与打开的页面相互干扰，导致自动化程序可能会运行异常，我们可以通过下面方式监测任何新的页面打开：

    @asynccontextmanager
    async def handle_expect_page(self, timeout: int = 3000):
        page: Union[Page, None] = None
        try:
            async with self.context.expect_page(timeout=timeout) as page_info:
                page = await page_info.value
                yield page

        except Exception as e:
            raise e
        
        finally:
            if page is not None:
                await page.close()

你只需要在在期望打开新页面之后调用它，他就会返回新页面的Page对象，如果超出时间没有任何页面打开则会报TimeoutError。注意，这里使用了@asynccontextmanager装饰器，你需要使用async with语句调用，或者你可以修改这个函数。

总结

通过以上代码，我们实现了在 Playwright 中自动处理验证码的功能。通过自定义的ClickSolver类，我们可以轻松地处理各种验证码，包括 Google reCAPTCHA 和 Cloudflare Turnstile。同时，我们还提供了Browser类来简化 Playwright 的使用，使得代码更加简洁和易读。 这个 Demo 只是演示如何处理 Cloudflare Turnstile 验证码，如果需要处理 Google reCAPTCHA 验证码，需要替换 captchatype=CaptchaType.CLOUDFLARETURNSTILE