荆仕航的博客站

前端工程师转 AI Agent 开发，我的学习路线

Tue, 19 May 2026 00:00:00 GMT

这篇文章不是一份“权威路线图”，而是我作为一名前端工程师，在转向 AI Agent / AI 应用开发过程中的阶段性思考和学习计划。

我希望把这个过程记录下来，一方面方便自己回顾，另一方面也给同样想从前端转向 AI 应用开发的同学一个参考。

一、为什么要转 AI Agent 开发？

让我决定拓宽方向的原因很直接：现在已经进入 AI 时代了，前端开发不会消失，但如果只会做前端，未来的路会越来越窄。

我过去 4 年主要做前端开发。以前，前端开发是一件很具体的事情，产品给出需求，设计给出页面，而我只需要负责把页面实现出来，把交互做好，接上接口，把异常处理掉，最后让用户可以稳定地使用这个功能。后来，前端开始涉及更多工程化、性能优化、组件设计和项目架构相关的内容，前端开发也不再只是单纯把页面写出来。而现在，AI 又把这个变化往前推了一步，各大小公司都在前赴后继地转向 AI，它不仅开始影响软件开发的方式，也开始影响前端工程师未来的能力边界。

我开始关注 AI Agent。AI Agent 是一种应用形态，它把大模型接入真实工具和业务流程，变成一个能帮人干活的系统。相比单纯调用大模型生成一段回答，AI Agent 更像是一个能理解任务、结合上下文、调用工具并完成具体工作的智能助手。它不只是“会聊天”，而是可以围绕一个目标去检索资料、分析问题、生成结果，甚至协助推进后续动作。

对我来说，在 AI 时代里，主动把自己的能力从单纯的前端开发，扩展到更完整的 AI Agent 开发，也算是在追热点。但这个热点不是短期噱头，而是一个正在改变软件开发和职业方向的长期趋势。

二、前端转 AI Agent 的跨度

一开始，我也想过先从 Python 学起。后来我想明白自己想做的到底是哪一层。学习 AI Agent 并不意味着放弃自己熟悉的技术栈，因为各大模型调用方式和各种工具，基本都有支持 Node.js 的开发方式。

在还没有接触机器学习、数据处理、模型训练这些更底层内容的时候，Python 并不是必须的。等后面熟悉 AI 应用开发之后，如果需要接触更底层的内容，再补 Python 会更合适。只是做 AI 应用，TypeScript + Node.js 完全可以作为起点。

AI 应用开发的重点，不是从零训练一个模型，而是如何把现有模型能力接入真实业务，让它在具体场景里产生价值。

调用大模型接口、实现流式输出、处理工具调用、接入数据库、做 RAG 检索、封装业务 API、做权限控制，这些事情 Node.js 都能完成。

对我来说，先用熟悉的 TypeScript 把 AI 应用开发的主线跑通，比一开始同时学习新语言、新框架、新概念要现实得多。现在很多主流开源项目，也有不少是用 TypeScript 做出来的。

所以我的选择是：先用自己熟悉的技术栈进入这个方向。后面遇到确实需要 Python 的场景，再补 Python，给自己找一个更容易启动的入口。

三、理解 AI Agent

我现在对 AI Agent 的理解是：AI Agent 是一个能够理解用户目标、结合上下文、调用工具，并在一定流程中自主完成任务的 AI 应用。

对比普通聊天机器人偏向的回答，Agent 更偏向做事。

比如用户问：“帮我整理一下这个项目最近的风险点，并列出每个风险对应的负责人。”

如果只是普通聊天，模型可能会给出一段很通用的建议，比如建议关注进度风险、技术风险、沟通风险。但这对真实工作帮助有限，因为它没有团队上下文，也不知道这个项目最近发生了什么。

一个更接近 Agent 的系统，应该能够去查项目文档、会议纪要、任务状态、历史问题，然后基于这些真实信息进行总结。如果它发现某个风险没有负责人，甚至可以继续提示需要补充责任人。再进一步，它还可以创建待办、发通知、生成日报，甚至接入更多工具，完成一些自动化操作。现在很多主流 Agent 产品，也都在快速增强这类能力。

当然，第一阶段我更关心的是先把几个核心问题弄明白：大模型如何接入，Prompt 如何设计，流式输出怎么做，模型如何调用工具，RAG 如何让回答基于知识库等。

这些看起来像一个个技术点，但串起来以后，其实就是 AI Agent 的基本骨架。当模型调用工具、检索知识、执行任务这些能力逐步串起来之后，AI Agent 才会从一个普通聊天入口，慢慢变成一个真正能参与工作流程的系统。

四、学习路线

学习 AI Agent 很容易被各种方向带着跑。

一会儿看到模型训练，一会儿看到微调；一会儿看到 RAG，一会儿又看到 Tool Calling、MCP、LangChain、LangGraph、向量数据库、工作流编排。每个概念都很重要，每个方向也都能继续深入。

但对我来说，现阶段最重要的不是一上来什么都学，而是先明确边界。如果不先划清边界，很容易什么都想学，最后什么都学得很浅。

我更想先解决的是：如何使用现有大模型能力，把大模型接入真实业务系统，让 AI 能力变成一个用户可以使用、工程上可以维护、后续可以扩展的应用能力。

所以，我给自己定的学习路线，会围绕 AI Agent 应用开发逐步展开。

1. 大模型调用和 Prompt Engineering

第一个阶段，先学会和大模型打交道。

这里不只是简单调一次接口，而是要理解大模型在应用里到底怎么工作。比如 system、user、assistant 这些消息角色分别起什么作用，模型参数会怎样影响输出。

同时，这一阶段也要学习 Prompt Engineering。

学习 Prompt 后会发现，Prompt 不只是“提示词”，而是一种和模型协作的任务说明书。它需要告诉模型当前任务是什么、输入内容是什么、输出格式是什么、有哪些限制、不确定时应该怎么处理。

很多时候模型回答不好，并不是模型笨，而是没有把任务、上下文和边界讲清楚。

这一阶段的目标，是先把大模型基础调用和 Prompt 设计跑通。至少能做出一个完整的聊天链路：用户输入问题，后端调用模型，能让模型按照相对稳定的格式返回内容。

2. 调用工具 Tool Calling

第二个阶段，学习 Tool Calling。

通俗来说，调用工具一方面是让模型判断自己要使用哪个工具，另一方面是把模型返回的指定格式数据作为参数传递给工具函数，最后把结果再回传给模型，以此给模型添加使用工具的能力。

模型本身并不知道外部系统里的实时数据，也不能凭空访问业务接口。如果希望它完成更具体的任务，就需要通过 Tool Calling 把模型和外部工具连接起来。

这一阶段需要重点理解：如何定义工具，如何描述工具能力，如何设计工具参数，如何校验模型传来的参数，如何执行工具，如何把工具结果再交还给模型。

工具调用看起来像是模型能力，但背后其实是工程设计。工具定义得不清楚，模型可能不知道什么时候该调用；参数设计得不合理，后端执行起来就会很混乱。

所以 Tool Calling 是 AI Agent 开发里非常核心的一步。

3. 检索增强生成 RAG

第三个阶段，学习 RAG。

大模型自身的知识是有限的。它不知道本地文档，不知道公司内部资料，也不知道某些实时变化的信息。如果直接让模型回答，它回答得可能会比较笼统，或者只是告诉我们可以去哪里查看。

RAG 的意义就在于：先从外部知识库检索相关内容，再让模型基于这些内容回答。

这一阶段需要理解 Embedding 是什么，为什么要把文本变成向量，向量数据库解决什么问题，文档如何切分，除了向量检索还有哪些检索方式，检索到的内容又如何放进上下文里交给模型。

RAG 看起来只是“检索 + 生成”，但真正做起来会遇到很多细节。比如 chunk 太大或太小都会影响效果，检索结果不准确会影响回答质量，上下文太长会增加成本和时间，没有检索到内容时也要控制模型的回答。

这一阶段的重点，不只是把 RAG 跑通，还要理解它在 AI Agent 里的位置：负责给模型补充外部知识，让回答不只依赖模型自身记忆。

4. Agent 工作流和任务编排

第四个阶段，学习 Agent 的工作流和任务编排。

当模型可以调用工具，也可以基于外部知识回答之后，下一步就是让它围绕一个目标完成多步骤任务。

这时就会涉及任务拆解、步骤规划、状态管理、上下文传递、工具调用顺序、失败重试等问题。

简单来说，AI Agent 不应该只是“调用一次模型，然后返回结果”。更完整的 Agent 往往需要经历一个过程：理解目标，判断需要哪些信息，决定是否调用工具，读取工具结果，再继续分析，最后生成结果。

这一阶段可以开始理解 Workflow、Planning、Memory、Multi-step Reasoning 这些概念。

对我来说，先理解一个 Agent 如何完成一个简单的多步骤任务，比一上来研究多个 Agent 怎么协作更重要。

走到这一步之后，就已经可以尝试做一个真实项目了。

5. AI Agent 工程化能力

第五个阶段，是补齐 AI Agent 的工程化能力。

真正做一个 AI Agent 应用，不只是写 Prompt，也不只是调用模型。它需要有完整的工程系统来支撑。

比如服务端要负责模型调用、会话管理、工具编排、上下文管理、数据存储、错误处理、日志记录和接口封装。前端要负责输入交互、流式展示、结果渲染、状态反馈和用户体验。

这一阶段我会以实践为主，继续用 TypeScript / Node.js 作为主要起点。后端服务可以选择 Hono、Koa，或者直接使用 NestJS；数据库选择 PostgreSQL，ORM 可以考虑 Prisma 或 Drizzle，向量数据库可以选择 Qdrant，异步任务后面可以通过 Worker 结合 Redis 和 BullMQ。

但我不会一开始就把所有技术都堆上去。

第一版最重要的是先跑通核心链路。等基础能力稳定之后，再逐步补上任务队列、日志、监控、安全和部署这些工程能力。

AI Agent 最终还是一个软件系统，所以工程化能力一定绕不开。

6. LangChain 和 LangGraph

等大模型调用、Prompt、Tool Calling、RAG 和基础 Agent 工作流跑通之后，我会开始学习 LangChain 和 LangGraph。这两个框架刚好也支持 TypeScript。

LangChain 更像是一个 AI 应用开发工具库，它把模型调用、Prompt、工具调用、RAG、记忆、链式调用等能力做了封装，可以帮助开发者更快搭建 AI 应用。

LangGraph 则更偏向 Agent 工作流编排。相比简单的一次模型调用，它更适合处理多步骤任务、状态流转、条件判断、循环执行和复杂 Agent 流程。

先用原生方式把核心流程跑通，再学习 LangChain 和 LangGraph。这样看框架时，就能更清楚它们到底解决了什么问题，也能更快上手和理解。

我的计划是：在真正需要 LangChain 或 LangGraph 之前，先进行下面的项目实践。等项目发展到确实需要框架能力时，再把它们逐步引入进来。

五、用项目实践检验学习路线

学习 AI Agent 最好的方式，肯定不是只看概念，而是做一个真实项目。

我目前要做的项目，是一个 AI 助理，同时也是在工作中需要的一个团队 AI 助理。

这个项目对我来说比较合适，因为它既有实际业务价值，又能把 AI 应用开发中的关键能力串起来。后续也能接入自己的知识库，以及为我的 blog 添加一个 AI 助理。

第一版团队 AI 助理先解决几个简单但真实的问题。

比如团队知识库问答。很多团队都有大量文档，但真正找起来很痛苦。业务规则、技术方案、流程规范、历史问题，可能散落在不同系统里。AI 助理如果能基于知识库回答，并且给出来源，就已经能节省很多重复沟通成本。

再比如日常工作跟进。团队每天都会产生进度、风险、待办、负责人这些信息。如果 AI 能帮助汇总这些内容，就可以减少一些机械整理工作。

会议辅助也是一个很自然的场景。会议结束后，AI 可以帮助提取结论、待办和责任人。现在的会议基本都能自动生成相关会议纪要，但这些纪要后续能不能被持续跟踪、快速检索，我想 AI 助理可以很好地解决这个问题。

我选择这个项目，不是因为它听起来最酷，而是因为它足够贴近真实工作。它会让我逐步思考数据来源、权限控制、回答可信度和用户体验这些问题。

能够做一个真实解决这些问题的项目，比单纯做一个聊天 Demo 更有意义，也更能得到成长。

六、总结

以上是我现阶段对 AI Agent 开发的学习路线。对我来说，这条路既不会完全脱离已有的工程经验，又能让我从单纯的前端开发，逐步扩展到更完整的 AI Agent 应用开发。

它可能会随着实践不断调整，但至少现在，我已经知道自己要从哪里开始了。

如果你也是前端开发，你肯定知道前端技术的更新迭代很快，学习新技术是一种常态 :)

这篇文章算是一个起点。后面我会继续记录学习 AI Agent / AI 应用开发的过程，更希望每篇都解决一个真实问题。

用 Astro 搭建个人博客：从零到上线的完整实践

Fri, 06 Feb 2026 00:00:00 GMT

为什么选择 Astro

首先排除SPA模式，思考了以下几种：

Next.js —— 太重，我只是写博客，不需要服务端渲染那套
Nuxt —— Vue 技术栈，但我更想试试新东西
VitePress —— 适合文档，博客功能不够灵活
Astro —— 静态生成、按需加载、支持 Vue/React 组件

最后选了 Astro，原因很简单：

够轻 —— 默认零 JavaScript，页面加载快，SEO 友好
够灵活 —— 可以用 Vue 写组件
够新 —— 2024 年之后火起来的，新技术意味着有探索空间，值得试试
部署简单 —— 静态站点，扔哪都能跑

实际用下来，挺满意的。下面记录一下搭建过程。包括我踩过的每一个坑。希望你的博客之路能比我顺畅一些。

项目架构

最初只是普通的静态博客，后来加了”个人动态”功能，就需要后端了，考虑到项目并不复杂，没必要分多个仓，于是就搞了个 Monorepo。后续有其他想法也会加入其他动态功能。

我有两个选择：

纯前端方案 —— 用第三方服务（例如文章的评论使用的 Giscus，后续有空会自己实现）
前后端分离 —— 自己写个简单的 API 服务

我选了第二个。原因很简单：我想掌握全部控制权，随意改动。

于是我的博客变成了这样：

blog/
├── apps/
│   ├── web/         # 前端 — Astro 静态博客
│   └── server/      # 后端 — Hono API 服务
├── package.json
├── pnpm-workspace.yaml
└── pnpm-lock.yaml

pnpm

pnpm 现代前端开发优选。它用硬链接的方式共享依赖，节省空间，速度快。对于 Monorepo 来说，pnpm 几乎是唯一选择。

技术栈

我的技术选型原则是：权衡利弊，刚刚好，不过度追求，不强行炫技。

技术	用途	选择理由
Astro 5.x	静态站点框架	核心理由：零 JS 默认，快
Vue 3.x	交互组件（个人动态页）	日常使用，生态丰富
Swup	页面无刷新过渡动画	让网站有点 SPA 的感觉，提升体验
CSS Variables	主题系统，使用 hsl()	原生支持，不用额外库，暗色模式轻松搞

有尝试过 Tailwind CSS，但觉得太重了，有些地方需要去了解默认的各种样式，然后选择原生 CSS + Less 简单方便。

目录结构

根据开发过程逐渐需要新的结构并参考优秀项目目录，最后形成了自己的规范：

apps/web/
├── public/                  # 静态资源（图片、字体）— 直接复制不构建
├── src/
│   ├── components/          # 组件 — 按功能模块分组
│   │   ├── aside/           # 侧边栏（作者卡片、分类、标签）
│   │   ├── blog/            # 博客组件（文章卡片、详情）
│   │   ├── header/          # 页头（导航、搜索、主题切换）
│   │   └── moments/         # 个人动态（Vue 组件，因为交互多）
│   ├── content/             # 内容集合 — Astro 的核心特性
│   │   └── blog/            # 博客文章（Markdown 文件都放这里）
│   ├── layouts/             # 页面布局 — 统一 header/footer
│   ├── pages/               # 页面路由 — 文件即路由
│   ├── plugins/             # Remark/Rehype 插件 — Markdown 增强
│   └── styles/              # 全局样式 — CSS Variables 定义
└── astro.config.mjs         # Astro 配置

几个设计原则：

按功能分组，而不是按类型 —— 比如 components/blog/ 里放所有博客相关的组件，而不是把所有组件平铺
Markdown 和代码分离 —— content/blog/ 只放 Markdown 文件，组件和逻辑放 src/
路由即文件 —— Astro 的 pages/ 目录结构直接对应 URL 路径，直观

核心功能实现

1. Markdown 内容管理

Astro 的 Content Collections 是我决定用它的重要原因之一。

我的文章 schema 定义：

const blog = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(), // 标题必填
    pubDate: z.coerce.date(), // 发布日期，自动解析
    updatedDate: z.coerce.date().optional(), // 可选
    description: z.string().optional(),
    tags: z.array(z.string()).default([]),
    category: z.string().optional(),
    draft: z.boolean().default(false), // 草稿模式
  }),
})

每篇文章的 Frontmatter 长这样：

---
title: '文章标题'
pubDate: '2026-03-12'
description: '文章描述'
tags: ['Astro', '博客']
category: '前端'
draft: false
---

正文内容...

2. 阅读时间统计

我注意到很多博客都有”预计阅读时间”这个功能。

我的做法如下：核心依赖是两个插件

mdast-util-to-string —— 提取 Markdown 的纯文本内容
reading-time —— 计算阅读时间

插件代码：

// src/plugins/remark-reading-time.ts
import { toString } from 'mdast-util-to-string'
import readingTime from 'reading-time'

export function remarkReadingTime() {
  return function (tree, file) {
    const textContent = toString(tree) // 提取纯文本
    const stats = readingTime(textContent) // 计算阅读时间

    // 把结果写入 Frontmatter
    file.data.astro.frontmatter.readingTime = {
      words: stats.words,
      minutes: Math.ceil(stats.minutes),
    }
  }
}

最后将 remarkReadingTime 插件添加到 Astro 配置中。

3. Markdown 样式：从 Tailwind 到自定义

Markdown 的渲染样式，我走过一段弯路。

最开始，我直接用了 @tailwindcss/typography 插件，几行配置就能让 Markdown 有不错的默认样式。但用了一段时间后发现：

Tailwind 的类名太多，调试起来麻烦
有些细节样式不符合我的设计
为了自定义一个颜色，得覆盖一堆类

后来，我干脆自己写了一套 Markdown 样式，用 Less 组织，按模块拆分：

styles/markdown/
├── markdown.css      # 基础排版（标题、段落、列表、表格）
└── markdown-code.css # 代码块样式（行号、复制按钮、滚动条）

代码块，自定义复制按钮：

用 CSS 画图标（SVG mask），不用额外图片
悬停时显示，点击后变勾选动画
复制成功有视觉反馈

提示

自定义样式虽然花时间，但完全可控，后期维护反而更轻松。

Markdown 插件方面，我加了这些：

remark-gfm —— GitHub Flavored Markdown，支持表格、删除线等
remark-github-admonitions-to-directives —— GitHub 风格的提示块（例如上方的提示 —— :::note、:::warning）
rehype-autolink-headings —— 标题自动生成锚点，点击可跳转
rehype-code-copy —— 代码块复制按钮（配合自定义样式）

4. Vue 组件集成：Astro 的 Island 架构

个人动态页（类似朋友圈）是我博客里动态数据的部分。有发布动态、图片上传、删除。

所以我用 Vue 写了这个页面。这也是 Astro “Island 架构”的典型应用——只有需要交互的部分才加载 JavaScript。

在 Astro 中使用 Vue 组件：

---
import MomentsPage from '../components/moments/MomentsPage.vue'
---

<MomentsPage client:load />

注意 client:load —— 这是 Astro 的指令，告诉它这个组件需要在客户端加载和渲染。

Astro 的几种客户端指令：

client:load —— 页面加载时立即加载（适合首屏交互）
client:idle —— 浏览器空闲时加载（适合非关键交互）
client:visible —— 滚动到可见区域时加载（适合长页面）
client:only —— 只在客户端渲染，构建时跳过（适合依赖浏览器 API 的组件）

坑：

一开始我忘了加客户端指令，部署后直接报错：“window is not defined”。

原因是 Astro 默认是服务端渲染（SSR），在构建时执行。而 window、document 这些浏览器 API 在服务端不存在。

加上 client:load 后，Astro 就知道这个组件要在客户端跑，构建时会跳过它。

5. 页面无刷新过渡：Swup 让体验更流畅

点击一个链接，页面一下切换，没有白屏，没有闪烁，像 SPA 一样流畅，这就是 Swup 做的事。

配置非常简单：

// astro.config.mjs
import swup from '@swup/astro'

export default defineConfig({
  integrations: [swup({ containers: ['#swup'] })],
})

然后在布局文件里给会变化的区域加个 id="swup"：

<main id="swup" data-swup>
  <slot />
</main>

过渡动画用 CSS 写，我用的默认淡入淡出，也可以自定义更复杂的效果。

使用上可能说不清哪里不一样，但会觉得”这个网站很流畅”。

6. 主题切换：HSL 让调色变得简单

暗色模式现在是标配了。我用 CSS Variables 实现，而且用 HSL 定义颜色。

HSL（色相、饱和度、亮度）比 RGB 更直观。比如我想让主题色饱和度高一点，在 HSL 里只需要调饱和度（S），而在 RGB 里不够直观，需要多次尝试。

想换主题色？只需要改 --hue 一个值，全站颜色自动更新
调亮度？改 --lig 就行

亮暗模式切换逻辑：优先使用用户上次选择的主题，如果没有，就跟随系统偏好。

const theme =
  localStorage.getItem('theme') || (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light')

document.documentElement.classList.toggle('dark', theme === 'dark')

注意： 我把这段代码放在 <head> 里，并使用 <script is:inline></script>，避免页面加载时闪烁（先亮后暗）。

构建优化

博客性能是我非常在意的。我用了几种优化手段：

1. 代码压缩

用 astro-compress 一站式压缩 CSS、JS、HTML。配置里我开启了所有选项：

CSS 压缩 + 移除注释
HTML 移除空白 + 移除注释
JS 压缩 + 移除 console.log

最后再加上 EdgeOne Pages 对网站的优化，gzip/brotli，效果明显。

2. 图片优化

图片通常是网站最大的资源。Astro 的 Image 组件会自动把图片转换成 WebP 格式（现代浏览器支持），并且按需加载。

或者可以通过 getImage API 手动处理图片压缩为 WebP/Avif 格式，也支持配置质量。

---
import { Image } from 'astro:assets'
import cover from '../images/cover.jpg'
---

<Image src={cover} alt="封面" />

好处：

自动裁剪不同尺寸，适配不同屏幕
懒加载，滚动到视口才加载
WebP 格式比 JPEG 小 30% 左右

3. Vite 配置优化

Astro 底层用 Vite，所以可以配置 Vite 的构建选项：

vite: {
  build: {
    minify: 'esbuild',      // 快速压缩
    cssCodeSplit: true,     // CSS 分割，按需加载
    target: 'esnext',       // 只针对现代浏览器
  }
}

4. SEO 与分享卡片优化

博客写好了。微信、QQ、Twitter 上看到的链接预览卡片，都是靠 SEO 标签实现的。

<!-- src/pages/blog/[slug].astro -->
<head>
  <meta property="og:title" content={frontmatter.title} />
  <meta property="og:description" content={frontmatter.description} />
  <meta property="og:image" content={ogImage} />
  <meta property="og:url" content={Astro.url} />
  <meta property="og:type" content="article" />
  <meta property="article:published_time" content={frontmatter.pubDate} />
  <meta property="article:author" content={frontmatter.author} />
</head>

效果： 分享链接时，自动显示文章标题、描述和封面图。

后端 API 服务：简单的力量

个人动态需要登录、发布、删除，所以需要一个后端。

我的原则是：够用就行，不搞复杂。

技术选型

技术	用途	选择理由
Hono	Web 框架	轻量、快速、TypeScript 友好
better-sqlite3	数据库	单文件、零配置、性能够用
jose	JWT 鉴权	现代、安全、API 简单

Hono 是我第一次用，体验很好。它的设计理念是”小”，整个框架只有几十 KB，但功能完整。

核心代码结构

apps/server/
├── src/
│   ├── db/           # 数据库连接
│   ├── middleware/   # JWT 鉴权中间件
│   ├── routes/       # API 路由
│   └── index.ts      # 入口

入口文件简单：

import { Hono } from 'hono'
import { cors } from 'hono/cors'

const app = new Hono()
app.use('/api/*', cors()) // 允许跨域
app.route('/api/auth', authRoutes) // 登录接口
app.route('/api/moments', momentRoutes) // 动态接口

export default app

JWT 鉴权中间件：

原理是：用户登录后发一个 JWT token，之后每次请求都带上这个 token。服务端验证 token 有效性，有效才允许操作。

export async function authMiddleware(c, next) {
  const token = c.req.header('Authorization')?.replace('Bearer ', '')

  if (!token) return c.json({ error: 'Unauthorized' }, 401)

  try {
    const payload = await verify(token, JWT_SECRET)
    c.set('user', payload)
    await next()
  } catch {
    return c.json({ error: 'Invalid token' }, 401)
  }
}

这段代码保护了所有需要登录的接口。

部署流程：从本地到线上

部署策略：

前端（web）：静态部署到腾讯云 EdgeOne Pages，CDN 加速，足够快而且免费够用
后端（server）：跑在腾讯云轻量应用服务器，包年也便宜

这样设计的好处是：前端完全静态，几乎零成本；后端按需部署，资源占用低。

域名

我用的是腾讯云的域名，绑定了两个子域名：

blog.jingshihang.cn：博客主站
server.jingshihang.cn：API 服务

图片/文件

图片和文件都放到腾讯云的 COS 对象存储里，访问速度快，便宜够用。

开启图片防盗链，只允许指定域访问图片

# 用 PM2 守护进程
pm2 start dist/index.js --name blog-server

PM2 是个进程管理工具，可以保证服务挂了自动重启。

Nginx 反向代理：

我用 Nginx 做反向代理，把 server.jingshihang.cn 的请求转发到本地 3001 端口。

server {
    listen 443 ssl;
    server_name server.jingshihang.cn;

    location / {
        proxy_pass http://localhost:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

踩坑记录：都是真金白银换来的

坑 1：Swup 页面切换后组件失效

用 Swup 做页面无刷新切换时，遇到一个问题：切换页面后，代码块复制按钮、评论系统、统计脚本都不工作了。

原因： Swup 只替换页面内容区域（<main id="swup">），但不会重新执行 <script> 标签。那些依赖 DOM 加载后初始化的脚本，在切换页面后就失效了。

解决： 监听 Swup 的 swup:content:replace 事件，在内容替换后重新初始化：

// 代码块复制按钮、评论系统、统计脚本、标题锚点滚动
document.addEventListener('swup:content:replace', initSomething)

关键点： 把需要初始化的逻辑封装成函数，首次加载时执行一次，每次 swup:content:replace 时再执行一次。

这个事件是 Swup 内容替换完成后触发的，是重新绑定事件、重新初始化组件的最佳时机。

坑 2：Shiki 代码高亮主题切换

Astro 默认用 Shiki 做代码高亮，支持双主题（亮色/暗色）。但自定义样式时踩了个坑：样式覆盖不了。

问题： 我想让代码块的背景色和网站主题更搭，但无论怎么写 CSS，Shiki 的内联样式都优先生效。

原因： Shiki 会在 <pre> 和 <span> 标签上直接写内联样式（style="background-color: #xxx"），优先级比外部 CSS 高。

解决： 必须用 !important 强制覆盖，而且暗色模式要用 Shiki 提供的 CSS 变量：

/* 亮色模式 - Shiki 默认用 --shiki-light */
.markdown-body pre.astro-code,
.markdown-body pre.astro-code span {
  background-color: var(--shiki-light-bg) !important;
}

/* 暗色模式 - 必须用 --shiki-dark */
html.dark .markdown-body pre.astro-code,
html.dark .markdown-body pre.astro-code span {
  color: var(--shiki-dark) !important;
  background-color: var(--shiki-dark-bg-custom) !important;
}

关键点：

!important 是必须的，不然优先级不够
暗色模式要用 var(--shiki-dark)，这是 Shiki 生成的变量
亮色模式默认用 var(--shiki-light)，可以不写

这个坑让我明白了：Shiki 的双主题机制是靠 CSS 变量 + 类名切换实现的，要覆盖样式就得用同样的方式，而且必须加 !important。

最后

博客搭好了，地址：就是当前看到的页面 https://blog.jingshihang.cn

整体用下来，Astro 给我的感觉是很友好的。

不做多余的事，不强迫用它的生态，不绑死在固定技术栈上。这种反而让它变得更灵活。

Monorepo 架构让前后端分离更清晰，部署也方便。虽然一开始配置麻烦了点，但方便后续维护，长期来看是值得的。

如果你也想搭博客

我的建议是：

先想清楚需求 —— 你需要一个什么样的博客？
选对工具 —— Astro 适合博客，Next.js 适合复杂应用
别过度设计 —— 够用就行，后续可以迭代，重要的是执行，不能空想

未来规划

博客不是一蹴而就的，我还有一些计划：

文章目录（TOC）组件和目录跳转
照片墙页面
评论系统集成（当前使用的 Giscus）
国际化支持（如果有外国朋友想看）

参考资源：

如果这篇文章对你有帮助，欢迎分享和交流！也欢迎来我的博客留言～

JavaScript 实现防抖和节流

Thu, 17 Mar 2022 00:00:00 GMT

1. 防抖(debounce)

当事件触发时，相应的函数并不会立即触发，而是会等待一定的时间；
当事件密集触发时，函数的触发会被频繁的推迟；
只有等待了一段时间也没有事件触发，才会真正的执行响应函数；

1.1 应用场景

例如: 输入框中频繁的输入内容 频繁的点击按钮，触发某个事件 监听浏览器滚动事件，完成某些特定操作 用户缩放浏览器的resize事件等等

1.2 简单实现

第一个参数为函数 fn, 第二个参数延迟时间 delay

function debounce(fn, delay) {
  // 1.定义一个定时器, 保存上一次的定时器
  let timer = null

  // 2.真正执行的函数
  const _debounce = function() {
    // 取消上一次的定时器
    if (timer) clearTimeout(timer)
    // 延迟执行
    timer = setTimeout(() => {
      // 外部传入的真正要执行的函数
      fn()
    }, delay)
  }

  return _debounce
}

至此, 已经实现了一个简单的防抖函数

1.3 绑定this和参数args

当原始函数有参数和需要用到this时, 可以给 _debounc 添加args接收参数并在调用函数fn时使用 fn.apply(this, args)

function debounce(fn, delay) {
  let timer = null
  // 原始函数的参数args
  const _debounce = function(...args) {
    if (timer) clearTimeout(timer)
    timer = setTimeout(() => {
      // 绑定this
      fn.apply(this, args)
    }, delay)
  }

  return _debounce
}

1.4 第一次是否执行

首次触发时是否立即执行接收一个参数 immediate, 定义一个默认值, 这里为false, 声明一个是否第一次激活的变量 isInvoke = false, 如果immediate && !isInvoke就执行函数并将 isInvoke = true, 如下代码

function debounce(fn, delay, immediate = false) {
  // 1.定义一个定时器, 保存上一次的定时器
  let timer = null
  let isInvoke = false    // 是否激活了立即执行

  // 2.真正执行的函数
  const _debounce = function(...args) {
    // 取消上一次的定时器
    if (timer) clearTimeout(timer)

    // 判断是否需要立即执行
    if (immediate && !isInvoke) {
      fn.apply(this, args)
      isInvoke = true     // 已经立即执行, 阻止下次触发的立即执行
    } else {
      // 延迟执行
      timer = setTimeout(() => {
        // 外部传入的真正要执行的函数
        fn.apply(this, args)
        isInvoke = false  // 将isInvoke初始化
      }, delay)
    }
  }

  return _debounce
}

1.5 增加取消方法

如果触发了事件又不需要了, 比如直接离开此位置, 增加取消功能防止事件触发带来意外不当

function debounce(fn, delay, immediate = false) {
  // 1.定义一个定时器, 保存上一次的定时器
  ...
  // 2.真正执行的函数
  const _debounce = function(...args) {
    ...
  }

  // 封装取消功能
  _debounce.cancel = function() {
    if (timer) clearTimeout(timer)
    timer = null
    isInvoke = false
  }

  return _debounce
}

使用时便可以直接使用cancel方法

function fn() {
  ...
}
const debounceAfterFn = debounce(fn, 1000)
// 使用取消方法
debounceAfterFn.cancel()

1.6 函数返回值

解决返回值问题, _debounce返回一个Promise, 调用原始函数fn时拿到返回值const result = fn.apply(this, args), 再调用 resolve(result) , 使用时通过.then获取返回值

// debounce.js
function debounce(fn, delay, immediate = false) {
  // 1.定义一个定时器, 保存上一次的定时器
  let timer = null
  let isInvoke = false

  // 2.真正执行的函数
  const _debounce = function(...args) {
    return new Promise((resolve, reject) => {
      // 取消上一次的定时器
      if (timer) clearTimeout(timer)

      // 判断是否需要立即执行
      if (immediate && !isInvoke) {
        const result = fn.apply(this, args)
        resolve(result)
        isInvoke = true
      } else {
        // 延迟执行
        timer = setTimeout(() => {
          // 外部传入的真正要执行的函数, 拿到函数返回值并调用resolve
          const result = fn.apply(this, args)
          resolve(result)
          isInvoke = false
          timer = null
        }, delay)
      }
    })
  }

  // 封装取消功能
  _debounce.cancel = function() {
    if (timer) clearTimeout(timer)
    timer = null
    isInvoke = false
  }

  return _debounce
}

防抖的使用

在html中引入写好的防抖函数的文件debounce.js

<input type="text">
<button id="cancel">取消</button>

<script src="debounce.js"></script>
<script>
  const inputEl = document.querySelector("input")
  let counter = 0

  const inputChange = function(event) {
    console.log(`触发第${++counter}次`, this, event)
    // 返回值
    return "aaaaaaaaaaaa"
  }

  // 防抖处理 将原本函数放入 debounce 作为参数, 之后直接使用 debounceChange 即可
  const debounceChange = debounce(inputChange, 3000, false)
  //文本框事件触发
  inputEl.oninput = (...args) => {
    // 这种调用方法需要重新绑定this, 所写的debounce函数是没有问题的, 在实际开发中使用相对这里会简单一点
    debounceChange.apply(inputEl, args).then(res => {
      console.log("Promise的返回值结果:", res)
    })
  }

  // 取消功能
  const cancelBtn = document.querySelector("#cancel")
  cancelBtn.onclick = function() {
    debounceChange.cancel()
  }
</script>

2. 节流(throttle)

如果这个事件会被频繁触发，那么节流函数会按照一定的频率来执行函数；
不管在这个中间有多少次触发这个事件，执行函数的频率总是固定的；

2.1 应用场景

例如: 鼠标移动事件 王者荣耀攻击键, 点击再快也是以一定攻速(频率)进行攻击等等

2.2 简单实现

时间间隔: interval; 当前时间: nowTime; 上次执行时间: lastTime

主要算出每次点击后剩余的时间
时间差 = 当前时间 - 上次执行时间
剩余时间 = 时间间隔 - 时间差 const remainTime = interval - (nowTime - lastTime) 判断当剩余时间 <= 0 时执行函数

每次执行完之后将 lastTime = nowTime

function throttle(fn, interval, options) {
  // 1.记录上一次的开始时间
  let lastTime = 0

  // 2.事件触发时, 真正执行的函数
  const _throttle = function() {

    // 2.1.获取当前事件触发时的时间
    const nowTime = new Date().getTime()

    // 2.2.使用当前触发的时间和之前的时间间隔以及上一次开始的时间, 计算出还剩余多长事件需要去触发函数
    const remainTime = interval - (nowTime - lastTime)
    if (remainTime <= 0) {
      // 2.3.真正触发函数
      fn()
      // 2.4.保留上次触发的时间
      lastTime = nowTime
    }
  }

  return _throttle
}

2.3 首次不触发leading和最后结束触发trailing

2.3.1 leading

初始值lastTime = 0, 所以第一次的nowTime - lastTime也会很大, interval减去很大的正数, 就会成为负数 < 0 所以默认第一次是执行的

如果 interval 不是特别大, 第一次就是执行的, 除非你设置的 interval 大于当前时间. 也就是从计算机元年(1970)到如今, 五十多年的频率, 这个节流可不简单 :)

如果想要第一次不执行, 拿到remainTime之前将 lastTime = nowTime 即可

function throttle(fn, interval, options = { leading: true, trailing: false }) {
  // 1.记录上一次的开始时间
  const { leading, trailing } = options
  let lastTime = 0

  // 2.事件触发时, 真正执行的函数
  const _throttle = function() {

    // 2.1.获取当前事件触发时的时间
    const nowTime = new Date().getTime()
    if (!lastTime && !leading) lastTime = nowTime

    // 2.2.使用当前触发的时间和之前的时间间隔以及上一次开始的时间, 计算出还剩余多长事件需要去触发函数
    const remainTime = interval - (nowTime - lastTime)
    if (remainTime <= 0) {
      // 2.3.真正触发函数
      fn()
      // 2.4.保留上次触发的时间
      lastTime = nowTime
    }
  }

  return _throttle
}

2.3.2 trailing

最后是否执行, 需要使用到定时器 setTimeout

首先定义一个定时器 timer = null
如果remainTime <= 0 判断 timer 不为空是就清除定时器并置空, 执行完函数后直接 return
否则判断 trailing 为 true 且 timer 为 null 时, 设置一个定时器, 延迟时间就是剩余时间 remainTime
通过 timer 执行函数后关于 lastTime 最后应该设置为什么, 取决于 leading 的值
- 当 leading 为 true 时, 相当于2.2简单实现, 将lastTime赋值当前时间, 这里重新获取当前时间 lastTime = new Date().getTime()
- 当 leading 为 false 时, 直接将 lastTime 初始化为0, 相当于2.3.1 leading, 为0时下次执行将会进入if (!lastTime && !leading) lastTime = nowTime
- 因此 lastTime = !leading ? 0 : new Date().getTime()

function throttle(fn, interval, options = { leading: true, trailing: false }) {
  // 1.记录上一次的开始时间
  const { leading, trailing } = options
  let lastTime = 0
  let timer = null

  // 2.事件触发时, 真正执行的函数
  const _throttle = function() {

    // 2.1.获取当前事件触发时的时间
    const nowTime = new Date().getTime()
    if (!lastTime && !leading) lastTime = nowTime

    // 2.2.使用当前触发的时间和之前的时间间隔以及上一次开始的时间, 计算出还剩余多长事件需要去触发函数
    const remainTime = interval - (nowTime - lastTime)
    if (remainTime <= 0) {
      if (timer) {
        clearTimeout(timer)
        timer = null
      }

      // 2.3.真正触发函数
      fn()
      // 2.4.保留上次触发的时间
      lastTime = nowTime
      return
    }

    if (trailing && !timer) {
      timer = setTimeout(() => {
        timer = null
        lastTime = !leading ? 0 : new Date().getTime()
        fn()
      }, remainTime)
    }
  }

  return _throttle
}

2.4 绑定原本函数的this和参数args && 增加取消方法和函数返回值

与防抖实现相同, 使用apply绑定this和传参数, 返回Promise来解决返回值问题最终代码如下:

function throttle(fn, interval, options = { leading: true, trailing: false }) {
  // 1.记录上一次的开始时间
  const { leading, trailing, resultCallback } = options
  let lastTime = 0
  let timer = null

  // 2.事件触发时, 真正执行的函数
  const _throttle = function(...args) {
    return new Promise((resolve, reject) => {
      // 2.1.获取当前事件触发时的时间
      const nowTime = new Date().getTime()
      if (!lastTime && !leading) lastTime = nowTime

      // 2.2.使用当前触发的时间和之前的时间间隔以及上一次开始的时间, 计算出还剩余多长事件需要去触发函数
      const remainTime = interval - (nowTime - lastTime)
      if (remainTime <= 0) {
        if (timer) {
          clearTimeout(timer)
          timer = null
        }

        // 2.3.真正触发函数
        const result = fn.apply(this, args)
        resolve(result)
        // 2.4.保留上次触发的时间
        lastTime = nowTime
        return
      }

      if (trailing && !timer) {
        timer = setTimeout(() => {
          timer = null
          lastTime = !leading ? 0: new Date().getTime()
          const result = fn.apply(this, args)
          resolve(result)
        }, remainTime)
      }
    })
  }

  _throttle.cancel = function() {
    if(timer) clearTimeout(timer)
    timer = null
    lastTime = 0
  }

  return _throttle
}

也可使使用回调函数callback来处理返回值

节流的使用

<input type="text">
<button id="cancel">取消</button>

<script src="throttle.js"></script>
<script>
  const inputEl = document.querySelector("input")
  let counter = 0
  const inputChange = function(event) {
    console.log(`触发第${++counter}次`, this, event)
    return 11111111111
  }

  // 节流处理
  const _throttle = throttle(inputChange, 3000, { 
    leading: false, 
    trailing: true,
  })
  inputEl.oninput = (...args) => {
    _throttle.apply(inputEl, args).then(res => {
      console.log("Promise的返回值结果:", res)
    })
  }

  // 取消功能
  const cancelBtn = document.querySelector("#cancel")
  cancelBtn.onclick = function() {
    _throttle.cancel()
  }
</script>

结语

学习自 coderwhy(王红元) 老师, 感谢老师