#Next.js 入门（二）：导航与链接

上一篇讲了怎么用文件夹定义路由，这篇讲怎么在路由之间跳转。

用过 react-router 的话，导航无非就是 <Link> 和 useNavigate。Next.js 也差不多，但因为页面默认跑在服务端，所以多了 prefetch、流式渲染这些东西。听着复杂，写起来其实没多少新东西。

#导航背后发生了什么

先花一分钟搞清楚原理，不然后面看 API 会觉得莫名其妙。

Next.js 页面默认是服务端组件，内容在服务器上生成再发给浏览器。那每次跳页面都要等服务器？那不是很慢？

还好，框架在背后做了三件事：

#Prefetch

<Link> 出现在屏幕上的时候，Next.js 就偷偷在后台把这个链接的页面数据加载好了。等你真点的时候，数据早就到了，所以感觉是秒开。

不过 prefetch 也分情况：

• 静态路由：整个页面都 prefetch
• 动态路由：不 prefetch，或者只 prefetch 到最近的 loading.tsx 那一层

#流式渲染

动态路由没法提前 prefetch，那就换个思路——服务器渲染好一块就先发一块，不用等整个页面都好了才发。配合 loading.tsx 的骨架屏，用户至少能先看到个加载状态，不会一直看着白屏。

#客户端过渡

传统 SSR 每次跳页面都是整页刷新，白屏闪一下。Next.js 的 <Link> 不走这套，它在客户端直接替换变化的部分，共享布局和状态都保留着，体验跟 SPA 没区别。

这三个东西配合起来，虽然页面是服务端渲染的，但用起来跟客户端渲染一样流畅。

#<Link> 组件

日常写得最多的就是它，react-router 里也有同名组件，用法差不多。

#基本用法

import Link from "next/link";

export default function Navigation() {
  return (
    <nav>
      <Link href="/">首页</Link>
      <Link href="/blog">博客</Link>
      <Link href="/about">关于</Link>
    </nav>
  );
}

跟 react-router 的区别：href 代替了 to，不需要额外的 <a> 标签（v13 之前需要）。

#动态路由链接

结合上一篇讲的动态路由，用模板字符串生成链接：

import Link from "next/link";

interface Post {
  slug: string;
  title: string;
}

export default function PostList({ posts }: { posts: Post[] }) {
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.slug}>
          <Link href={`/blog/${post.slug}`}>{post.title}</Link>
        </li>
      ))}
    </ul>
  );
}

href 也可以传对象：

<Link
  href={{
    pathname: "/blog/[slug]",
    query: { slug: post.slug },
  }}
>
  {post.title}
</Link>

两种写法效果一样，我个人更喜欢模板字符串，直观。对象写法参数多的时候可能更清晰一点。

#常用 Props

#替换历史记录

默认每次导航都会往浏览器历史栈里 push 一条。不想让用户点返回回到当前页？加个 replace：

<Link href="/dashboard" replace>
  进入仪表盘
</Link>

比如登录成功后跳仪表盘，用户不该再回到登录页。

#控制滚动行为

默认跳转后会滚到页面顶部（如果目标页面不在视口内的话）。不想要这个行为：

<Link href="/blog" scroll={false}>
  博客
</Link>

也可以用 # 锚点滚动到指定位置：

<Link href="/blog/intro#section-2">跳到第二节</Link>

#控制 Prefetch

一般不用管，框架自己处理。但如果页面上链接特别多（比如无限滚动列表），全 prefetch 太浪费了，可以关掉：

<Link href={`/products/${id}`} prefetch={false}>
  {name}
</Link>

#拦截导航

onNavigate 可以在跳转前拦一下，比如表单还没保存，用户就要走：

<Link
  href="/other-page"
  onNavigate={(e) => {
    if (hasUnsavedChanges) {
      e.preventDefault();
      // 弹窗确认
    }
  }}
>
  离开
</Link>

注意这个回调只在客户端导航时触发，Ctrl/Cmd + 点击开新标签页不会走这里。

#useRouter Hook

<Link> 是写在 JSX 里的，useRouter 是写在逻辑里的——表单提交完跳转、判断条件后跳转，这种场景用它。

"use client";

import { useRouter } from "next/navigation";

export default function LoginForm() {
  const router = useRouter();

  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault();
    const success = await login();
    if (success) {
      router.push("/dashboard");
    }
  }

  return <form onSubmit={handleSubmit}>{/* ... */}</form>;
}

两个容易踩的坑：

1. 必须加 "use client"，hook 只能在客户端组件里用
2. 从 next/navigation 导入，别写成 next/router，那是老版 Pages Router 的

#常用方法

#push vs replace

跟 <Link> 的 replace prop 一样的逻辑：

// 用户可以点返回回到当前页
router.push("/dashboard");

// 用户点返回会跳过当前页
router.replace("/dashboard");

#refresh 挺好用的

router.refresh() 会让服务端组件重新从服务器拿数据、重新渲染，但客户端组件的状态不会丢（useState 的值、滚动位置都还在）。

async function handleDelete(id: string) {
  await deletePost(id);
  router.refresh(); // 重新获取列表数据，UI 自动更新
}

react-router 里没有对应的东西，这算是服务端组件带来的新能力。

#<Link> 还是 useRouter

原则很简单：能用 <Link> 就用 <Link>，自动 prefetch、语义化都有了。useRouter 留给那些非得用代码控制的场景。

#usePathname：拿当前路径

返回当前 URL 的路径部分，不含查询参数和 hash。用得最多的地方就是导航高亮：

"use client";

import Link from "next/link";
import { usePathname } from "next/navigation";

const links = [
  { href: "/", label: "首页" },
  { href: "/blog", label: "博客" },
  { href: "/about", label: "关于" },
];

export default function Navigation() {
  const pathname = usePathname();

  return (
    <nav>
      {links.map((link) => (
        <Link
          key={link.href}
          href={link.href}
          style={{
            fontWeight: pathname === link.href ? "bold" : "normal",
          }}
        >
          {link.label}
        </Link>
      ))}
    </nav>
  );
}

只返回路径，不带查询参数。查询参数要用下面的 useSearchParams。

#useSearchParams：读查询参数

返回一个只读的 URLSearchParams 对象，就是 URL 里 ? 后面那部分。

"use client";

import { useSearchParams } from "next/navigation";

export default function SearchResults() {
  const searchParams = useSearchParams();
  const query = searchParams.get("q"); // /search?q=nextjs → "nextjs"
  const page = searchParams.get("page"); // /search?q=nextjs&page=2 → "2"

  return (
    <div>
      <p>搜索：{query}</p>
      <p>第 {page ?? 1} 页</p>
    </div>
  );
}

#常用方法

#更新查询参数

useSearchParams 本身是只读的，改参数得配合 useRouter 或 <Link>：

"use client";

import { useRouter, useSearchParams, usePathname } from "next/navigation";

export default function Pagination() {
  const router = useRouter();
  const pathname = usePathname();
  const searchParams = useSearchParams();

  function goToPage(page: number) {
    const params = new URLSearchParams(searchParams.toString());
    params.set("page", page.toString());
    router.push(`${pathname}?${params.toString()}`);
  }

  return (
    <div>
      <button onClick={() => goToPage(1)}>第 1 页</button>
      <button onClick={() => goToPage(2)}>第 2 页</button>
    </div>
  );
}

#服务端组件里怎么读

服务端组件用不了 hook，但 page.tsx 有个 searchParams prop：

// src/app/search/page.tsx（服务端组件）
export default async function SearchPage({
  searchParams,
}: {
  searchParams: Promise<{ q?: string; page?: string }>;
}) {
  const { q, page } = await searchParams;
  const results = await fetchResults(q, Number(page) || 1);

  return <div>{/* 渲染搜索结果 */}</div>;
}

#用哪个

#别忘了包 <Suspense>

这里有个坑：静态渲染的路由里用了 useSearchParams，会导致从这个组件往上到最近的 <Suspense> 边界全部变成客户端渲染。所以记得包一层 <Suspense>：

import { Suspense } from "react";
import SearchResults from "./SearchResults";

export default function SearchPage() {
  return (
    <Suspense fallback={<div>加载中...</div>}>
      <SearchResults />
    </Suspense>
  );
}

这样 <Suspense> 外面的部分还能正常静态渲染，不会被影响到。

#redirect：服务端重定向

用在服务端组件、Server Action、Route Handler 里，把用户重定向到另一个 URL。

import { redirect } from "next/navigation";

async function checkAuth() {
  const session = await getSession();
  if (!session) {
    redirect("/login");
  }
}

export default async function DashboardPage() {
  await checkAuth();
  return <div>仪表盘内容</div>;
}

#redirect vs permanentRedirect

为什么是 307/308 而不是 302/301？因为 302 会把 POST 请求变成 GET，307 会保留原始请求方法。这在表单提交场景下很重要。

#注意事项

• redirect 内部是靠抛异常来中断渲染的，别放在 try/catch 里，会被吞掉
• 不用写 return redirect(...)，TypeScript 类型是 never
• 客户端组件里只能在渲染过程中调 redirect，事件处理器里要用 useRouter

#原生 History API

浏览器自带的 window.history.pushState 和 replaceState 也能用，Next.js 会自动跟路由器同步。

#pushState：加一条历史记录

只想改 URL 不想触发页面导航的时候用，比如排序：

"use client";

import { useSearchParams } from "next/navigation";

export default function SortProducts() {
  const searchParams = useSearchParams();

  function updateSorting(sortOrder: string) {
    const params = new URLSearchParams(searchParams.toString());
    params.set("sort", sortOrder);
    window.history.pushState(null, "", `?${params.toString()}`);
  }

  return (
    <div>
      <button onClick={() => updateSorting("asc")}>升序</button>
      <button onClick={() => updateSorting("desc")}>降序</button>
    </div>
  );
}

#replaceState：替换当前那条

不需要用户能回退的场景，比如切语言：

"use client";

export default function LocaleSwitcher() {
  function changeLocale(locale: string) {
    window.history.replaceState(null, "", `/${locale}`);
  }

  return (
    <div>
      <button onClick={() => changeLocale("zh")}>中文</button>
      <button onClick={() => changeLocale("en")}>English</button>
    </div>
  );
}

跟 useRouter 的区别：这俩只改 URL，不会触发导航、不会重新拿数据。就是想让 URL 反映当前状态，但页面不用动。

#导航 API 一览

#导航慢？查查这几个原因

实际开发中如果觉得页面跳转卡，大概率是这几个问题：

1. 动态路由没写 loading.tsx — 浏览器干等服务器渲染完，用户看到的就是卡住了。加个 loading.tsx 马上就有加载状态，体感完全不一样。

2. 该静态的路由变成了动态 — 动态路由段忘了加 generateStaticParams，本来构建时就能生成的页面，变成每次请求都要现算。

3. 网络不好 — prefetch 还没完成用户就点了，数据没到位。可以用 useLinkStatus hook 加个加载指示器，至少让用户知道在转。

4. JS bundle 太大 — <Link> 要水合完才能开始 prefetch，bundle 大了水合就慢，prefetch 也跟着延迟。

#本文源码示例代码已上传至 GitHub：https://github.com/Colin3191/nextjs-demo

#Next.js 入门（一）：App Router 项目结构与路由

#Next.js 是什么

Next.js 是 Vercel 维护的 React 全栈框架，开箱就有文件路由、SSR/SSG、API 路由、自动代码分割这些能力。用过 React 的话可以这么理解：React 管 UI，剩下的事 Next.js 都包了。

我之前写 React 项目，路由要装 react-router，SSR 要自己配，代码分割要折腾 lazy loading。换到 Next.js 之后发现这些都不用操心了，框架通过文件约定帮你处理好了。所以学 Next.js 的重点其实就是搞懂这些约定。

#创建项目

pnpm create next-app@latest nextjs-demo --yes
cd nextjs-demo
pnpm dev

--yes 跳过所有交互提示，直接用默认配置（TypeScript、ESLint、Tailwind CSS、src/ 目录、App Router）。跑起来之后打开 http://localhost:3000 能看到欢迎页就行。

#项目结构

nextjs-demo/
├── src/
│   └── app/                  # ⭐ 路由核心目录
│       ├── layout.tsx         # 根布局（必须有）
│       ├── page.tsx           # 首页 /
│       └── globals.css        # 全局样式
├── public/                    # 静态资源，/文件名 直接访问
├── next.config.ts             # Next.js 配置
├── tsconfig.json              # TypeScript 配置
├── package.json               # 依赖和脚本
└── postcss.config.mjs         # PostCSS 配置

刚开始只需要关注三个地方：

• src/app/ — 写页面的地方，这篇文章基本都在讲它
• public/ — 放图片、字体之类的静态文件
• .next/ — 构建产物，别提交到 git 就行

根目录那一堆配置文件先不用管，默认的就够用。

#路由特殊文件

App Router 有一套文件命名约定，放在路由文件夹下的这些文件名会被框架识别：

渲染的时候它们是一层套一层的：

layout → template → error → loading → not-found → page

如果你写过 React，loading.tsx 其实就是 <Suspense fallback={...}>，error.tsx 就是 ErrorBoundary。只不过 Next.js 把它们变成了文件，不用你手动写了。

#文件即路由

这是 App Router 最核心的东西：文件夹结构就是 URL 结构。

用过 react-router 的话需要转变一下思路——没有集中式的路由配置了，你建什么文件夹，URL 就长什么样。

#基本路由

每个有 page.tsx 的文件夹就是一个路由：

// src/app/page.tsx → /
export default function Home() {
  return <h1>首页</h1>;
}

// src/app/blog/page.tsx → /blog
export default function Blog() {
  return <div>博客列表</div>;
}

// src/app/about/page.tsx → /about
export default function About() {
  return <div>关于我们</div>;
}

没有 page.tsx 的文件夹不会变成路由，所以你可以放心在 app/ 下面放组件、工具函数什么的，不会被意外暴露出去。官方管这个叫 colocation（就近放置）。

#嵌套路由

文件夹套文件夹，URL 就跟着嵌套：

src/app/
├── page.tsx                        → /
├── blog/
│   ├── page.tsx                    → /blog
│   └── first-post/
│       └── page.tsx                → /blog/first-post
└── dashboard/
    ├── page.tsx                    → /dashboard
    └── settings/
        └── page.tsx                → /dashboard/settings

#动态路由

文件夹名用方括号包起来就能匹配动态参数：

// src/app/blog/[slug]/page.tsx
export default async function Post({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  return <h1>文章：{slug}</h1>;
}

访问 /blog/hello-world 的时候，slug 就是 "hello-world"。

动态路由有三种写法：

react-router 里 [slug] 相当于 :slug，[...slug] 相当于 *，只是定义方式从路由配置变成了文件夹名。

#layout.tsx

Layout 是另一个核心概念。

#根布局

src/app/layout.tsx 是整个应用的根布局，必须有，而且必须包含 <html> 和 <body>：

import type { Metadata } from "next";
import "./globals.css";

export const metadata: Metadata = {
  title: "My App",
  description: "我的第一个 Next.js 应用",
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="zh-CN">
      <body>{children}</body>
    </html>
  );
}

children 就是当前路由的页面内容，所有页面都会被这个布局包着。

#嵌套布局

在子路由文件夹里也可以放 layout.tsx，只影响这个路由和它下面的子路由：

// src/app/blog/layout.tsx
export default function BlogLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <div style={{ display: "flex" }}>
      <nav style={{ width: 200 }}>
        <h2>博客导航</h2>
        <ul>
          <li>最新文章</li>
          <li>分类</li>
          <li>标签</li>
        </ul>
      </nav>
      <main style={{ flex: 1 }}>{children}</main>
    </div>
  );
}

这样 /blog 和 /blog/first-post 都有侧边栏，/about 不受影响。

有个细节值得注意：layout 在页面切换时不会重新渲染。从 /blog 跳到 /blog/first-post，BlogLayout 不会卸载重建，里面的状态会保留。这个行为在 react-router 里需要额外处理，Next.js 默认就是这样。如果你就是想每次都重新渲染，用 template.tsx 替代就行。

#路由分组和私有文件夹

#路由分组

文件夹名用圆括号包起来，不会出现在 URL 里，纯粹用来组织代码：

src/app/
├── (marketing)/
│   ├── layout.tsx          # marketing 专用布局
│   ├── page.tsx            → /
│   └── about/
│       └── page.tsx        → /about
├── (shop)/
│   ├── layout.tsx          # shop 专用布局
│   ├── cart/
│   │   └── page.tsx        → /cart
│   └── products/
│       └── page.tsx        → /products

(marketing) 和 (shop) 不影响 URL，但可以各自有独立的布局。适合按业务模块拆分代码，或者给不同模块套不同的布局。甚至可以搞多个根布局——把顶层的 layout.tsx 删了，每个分组里各写一个。

#私有文件夹

下划线 _ 开头的文件夹会被路由系统忽略：

src/app/blog/
├── _components/
│   └── PostCard.tsx        # 不会变成路由
├── _lib/
│   └── api.ts              # 不会变成路由
└── page.tsx                → /blog

其实没有 page.tsx 的文件夹本来就不会生成路由，但加个 _ 前缀意图更明确，也能避免跟 Next.js 以后可能新增的特殊文件名撞车。

#并行路由和拦截路由

这两个是进阶玩法，刚入门知道有这回事就行，用到再学。

#并行路由

@slot 命名的文件夹可以在同一个布局里同时渲染多个页面：

src/app/dashboard/
├── @analytics/
│   └── page.tsx
├── @team/
│   └── page.tsx
├── layout.tsx              # 同时接收 analytics 和 team
└── page.tsx

典型场景是仪表盘，多个面板各自独立加载、独立处理错误。

#拦截路由

用特殊的括号语法可以在当前布局里渲染另一个路由的内容：

最常见的用法：列表页点击某一项，弹个 Modal 显示详情，URL 变了但没离开当前页面。

#本文源码示例代码已上传至 GitHub：https://github.com/Colin3191/nextjs-demo

#LangChain.js RAG 实战（上）：环境搭建与文档处理

随着大模型技术的普及，RAG（检索增强生成）已成为企业级应用的标配。作为前端开发者，我们可以直接利用熟悉的 JavaScript/TypeScript 技术栈来构建强大的 AI 应用。本文是我学习 LangChain.js 的学习笔记，记录了从零开发 RAG 应用的过程。

#目录

• 什么是 RAG
• 为什么需要 RAG
• RAG 的应用场景
• RAG 的核心概念
• 技术栈选择
• 环境准备
• Document 抽象详解
• 文档加载器
• 示例：加载 PDF 文档
• 文本分割的重要性
• RecursiveCharacterTextSplitter 详解
• 实战：加载与分割
• 最佳实践
• 常见问题

#什么是 RAG

RAG（Retrieval-Augmented Generation，检索增强生成） 听起来很高大上，其实原理特别简单。

你可以把它想象成开卷考试。

• 传统的 LLM（闭卷考试）：模型全靠训练时“背”下来的知识回答。如果问它最新的新闻，或者公司内部的私密数据，它要么说不知道，要么就开始一本正经地胡说八道（幻觉）。
• RAG（开卷考试）：当用户提问时，系统先去翻阅你提供的“教科书”（知识库），找到相关的段落，然后把这些段落连同问题一起扔给 LLM。LLM 看着参考资料回答，自然就准确多了。

技术上的流程是这样的：

1. 检索：根据用户的问题，从知识库中找到相关的文档
2. 增强：将这些相关文档作为上下文，与用户的问题一起提供给大语言模型
3. 生成：大模型基于检索到的上下文生成准确的答案

#一个简单的例子

想象你在向一个助手提问：

用户："Nike 2023 年的收入是多少？"

没有 RAG 的 LLM：

可能会回答不知道，或者给出过时/错误的信息（因为模型的训练数据有限）

有 RAG 的 LLM：

1. 先从 Nike 2023 年的财务报告中检索到相关段落
2. 将这些段落作为上下文提供给模型
3. 模型基于准确的信息回答：Nike 2023 年的收入是 512 亿美元

#为什么需要 RAG

• 解决幻觉问题：强制模型参考真实文档，减少编造信息
• 突破知识截止：实时更新知识库，获取最新信息
• 可验证的来源：提供答案出处，增加可信度
• 保护隐私安全：基于企业内部文档构建私有知识库

#RAG 常见的应用场景

• 企业知识库问答：员工快速查找公司政策、技术文档、流程规范
• 智能客服系统：24*7 自动回答客户常见问题
• 文档分析与理解：快速从长篇报告中提取关键信息

#RAG 的核心概念

理解 RAG 需要掌握几个核心概念。

#1. 文档向量化（Embedding）

问题：计算机如何理解"苹果手机"和"iPhone"是相似的概念？

解决：将文本转换为数字向量（一组数字），语义相近的文本在向量空间中距离更近。

示例：

"苹果手机"  →  [0.23, -0.45, 0.78, ...]
"iPhone"    →  [0.25, -0.43, 0.76, ...]
"香蕉"      →  [-0.67, 0.34, -0.12, ...]

前两个向量的距离很近，表示它们语义相似。

#2. 向量相似度

余弦相似度（Cosine Similarity）是最常用的计算方法：

• 1 = 完全相同
• 0 = 完全不相关
• -1 = 完全相反

#3. RAG 的基本流程

┌─────────────────────────────────────────────────────────────┐
│                        RAG 完整流程                          │
└─────────────────────────────────────────────────────────────┘

  用户问题
     │
     ▼
┌─────────────┐
│  向量化查询  │  将问题转换为向量
└─────────────┘
     │
     ▼
┌─────────────────────────────────────┐
│        向量搜索（检索阶段）          │
│  • 在向量库中找到最相似的文档块      │
│  • 通常返回 top-k 个结果            │
└─────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────┐
│        构建提示词（增强阶段）        │
│  • 将检索到的文档作为上下文          │
│  • 与用户问题组合成完整的 prompt     │
└─────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────┐
│        LLM 生成答案（生成阶段）      │
│  • 基于上下文生成准确的回答          │
│  • 可以引用来源                      │
└─────────────────────────────────────┘
     │
     ▼
   返回答案

简单来说，就是先把知识切碎（向量化），存起来（索引）；等用户问的时候，搜出相关的碎片（检索），拼在一起给 AI 看（增强），最后让 AI 回答（生成）。

#技术栈选择

#为什么选择 LangChain.js？

说实话，市面上关于 LangChain 的教程 90% 都是 Python 的。那我为什么还要头铁选 JS 版？

1. 前端友好：作为前端出身，实在不想为了写个 Demo 再去折腾 Python 的虚拟环境、包管理那些东西。能用 TypeScript 搞定全栈，何乐而不为？
2. 全栈整合：现在的 Next.js / NestJS 应用直接集成 LangChain.js 非常顺滑，不用再单独起一个 Python 服务做中间层。
3. 类型安全：TypeScript 的类型提示在处理复杂的数据流时真的救命，比 Python 猜类型舒服多了。

虽然 JS 版的文档有时候更新比 Python 版慢半拍，但社区活跃度很高，坑基本都能填上。

#环境准备

开始搭建 RAG 应用的开发环境。

#1. 前置要求

• Node.js：建议 v18 或更高版本
• 包管理器：pnpm、npm 或 yarn
• 代码编辑器：VS Code

#2. 创建项目

# 创建项目目录
mkdir langchain-rag-demo
cd langchain-rag-demo

# 初始化 npm 项目
npm init -y

# 或者使用 pnpm
pnpm init

#3. 安装依赖

#基础依赖

# 核心包
pnpm add @langchain/core @langchain/community

# 文档加载器（PDF、文本等）
pnpm add pdf-parse@1

# 文本分割器
pnpm add @langchain/textsplitters

# 环境变量管理
pnpm add dotenv

#Embedding 服务（本文使用 Ollama）

# Ollama（本地模型，无需 API key）
pnpm add @langchain/ollama

#向量存储

# 开发环境：使用内存存储（用于学习，无需额外安装）

#4. 配置环境变量

创建 .env 文件（Ollama 无需 API key）：

# Ollama（本文使用）
# 无需 API key，确保 Ollama 服务运行即可
# 默认地址：http://localhost:11434

# 阿里云百炼（可选，作为备选方案）
# DASHSCOPE_API_KEY=sk-your-dashscope-key-here

⚠️ 注意：不要将 .env 文件提交到 Git，添加到 .gitignore：

echo ".env" >> .gitignore
echo "node_modules" >> .gitignore

#5. 配置 TypeScript

直接复制即可：

{
  "compilerOptions": {
    "moduleDetection": "force",
    "module": "nodenext",
    "target": "es2022",
    "moduleResolution": "nodenext",
    "allowJs": true,
    "esModuleInterop": true,
    "isolatedModules": true,
  },
}

添加运行脚本（package.json）：

{
  "scripts": {
    "rag": "tsx src/rag/index.ts"
  },
  "type": "module"
}

安装开发依赖：

pnpm add -D typescript tsx @types/node

#Document 对象：万物皆可 Document

在 LangChain 的世界里，不管你读的是 PDF、网页、Markdown 还是 Word，最终都会被统一封装成 Document 对象。

理解它的结构非常简单，它就两个核心属性：

interface Document {
  pageContent: string;            // 文本内容
  metadata: Record<string, any>;  // 元数据（来源、页码、作者等）
}

#为什么 Metadata 很重要？

很多新手容易忽略 metadata，只关注文本内容。但在实际的 RAG 应用中，元数据是精准检索的关键。

比如，当用户问“Nike 2023 年的营收是多少？”时，如果你在检索时能通过元数据过滤掉 year: 2022 的文档，准确率直接翻倍。

#Document 对象示例

虽然我们通常从文件加载文档，但也可以手动创建 Document 对象来理解其结构：

import { Document } from "@langchain/core/documents";

const doc = new Document({
  pageContent: "Nike 是一家全球知名的运动品牌，成立于 1967 年。",
  metadata: {
    source: "nike-info",
    category: "company",
  },
});

console.log(doc.pageContent);
// 输出: Nike 是一家全球知名的运动品牌，成立于 1967 年。

#Embedding 服务示例

本文使用 Ollama 本地模型（完全免费、无需 API key）。

#什么是向量维度？

向量维度（Vector Dimension）指的是 Embedding 模型生成的数字向量的长度。

简单来说，维度越高，能表达的语义越丰富，但计算和存储成本也越高。本文使用的 nomic-embed-text 模型生成的向量维度是 768。

#使用 Ollama Embeddings

import { OllamaEmbeddings } from "@langchain/ollama";

const embeddings = new OllamaEmbeddings({
  model: "nomic-embed-text",
  baseUrl: "http://localhost:11434",
});

// 生成向量
const vector = await embeddings.embedQuery("Nike 是一家运动品牌");
console.log(`向量维度: ${vector.length}`);  // 输出：768
console.log(`前 10 个值: ${vector.slice(0, 10)}`);  // 示例：[-0.23, 0.45, ...]

使用 Ollama 前的准备：

1. 安装 Ollama：

# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.com/install.sh | sh

2. 拉取 embedding 模型：

# 推荐模型（性能好、体积小）
ollama pull nomic-embed-text

3. 启动 Ollama 服务：

ollama serve

4. 验证安装：

curl http://localhost:11434/api/tags

说明：Ollama 完全免费，数据在本地运行。如果硬件配置较低，可以使用阿里云百炼等云服务。

#文档加载器：把数据喂给 LLM

LangChain 提供了极其丰富的加载器（Loaders），几乎支持所有你能想到的数据源。

#常用加载器一览

• PDFLoader: 处理 PDF 文件（本文重点）。
• TextLoader: 处理 .txt、.md 等纯文本。
• CSVLoader / JSONLoader: 处理结构化数据。
• CheerioWebBaseLoader: 爬取网页内容。
• NotionLoader / GitHubLoader: 对接第三方工具。

你可以在 LangChain 官方文档 中找到几百种集成。但在实际开发中，PDF 和 Markdown 是最常见的两种格式。

#示例：加载 PDF 文档

我们直接进入实战，使用 Nike 2023 年财务报告（10-K 文件）作为案例。

#准备工作

项目中的 PDF 文件路径：

src/rag/data/nke-10k-2023.pdf

如需下载，可以从以下位置获取：

• LangChain GitHub

#示例 1：基础 PDF 加载

import { PDFLoader } from '@langchain/community/document_loaders/fs/pdf';
import path from 'path';
import { fileURLToPath } from 'url';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

const pdfPath = path.join(__dirname, 'data', 'nke-10k-2023.pdf');
const loader = new PDFLoader(pdfPath);

const docs = await loader.load();

#文本分割的重要性

#为什么需要文本分割？

加载完文档后，下一步是将长文档分割成更小的文本块（chunks）。这是因为：

#1. LLM 的上下文窗口限制

• GPT-3.5：4K tokens（约 3000 个单词）
• GPT-4：8K-32K tokens
• Claude 2：100K tokens
• 本地模型：通常更小

如果文档太长，LLM 无法一次性处理。

#2. 提高检索精度

❌ 不分割的情况：
整个 100 页的 PDF → 一个向量
→ 检索时只能返回整篇文档
→ 精确度低

✅ 分割后：
每 500-1000 字符 → 一个向量
→ 检索时返回相关段落
→ 精确度高

#3. 避免信息"冲淡"

假设你在查询 "Nike 的毛利率"：

• 大文档：包含大量无关信息，相关的毛利率信息被"冲淡"
• 小文档：集中在毛利率段落，更容易被检索到

#4. 节省成本

• 向量化更小的文本块更便宜
• 检索和生成的 token 数更少
• 减少 LLM 的处理时间

#分割的挑战

文本分割不是简单的"按字符数切分"，需要考虑：

1. 语义完整性：不要在句子中间切断
2. 上下文连贯性：保留足够的上下文
3. 信息不丢失：重要信息不能被分割到两个块
4. 大小适中：每个块不能太大或太小

#RecursiveCharacterTextSplitter 详解

LangChain 提供了多种文本分割器，其中 RecursiveCharacterTextSplitter 是最推荐的通用选择。

#工作原理

它按优先级递归地尝试不同的分隔符。如果一段文本用第一个分隔符分割后仍然超过 chunkSize，它会拿那一段继续用下一个分隔符分割，而不是只分割一次。

1. 段落分隔符  - 优先级最高
2. 句子分隔符 . 或 ! 或 ?
3. 单词分隔符 (空格)
4. 字符级分割 - 最后手段

#核心参数

import { RecursiveCharacterTextSplitter } from "@langchain/textsplitters";

const textSplitter = new RecursiveCharacterTextSplitter({
  keepSeparator: false,      // 是否在输出中保留分隔符（可选）
  lengthFunction: (text) => text.length,  // 计算长度的函数（可选）
});

💡 避坑指南：字符 vs Token

在 LangChain.js 中，默认的 chunkSize 是基于字符数（Characters）计算的。而大模型的上下文窗口（Context Window）是基于 Tokens 计算的。

• 对于英文：1 个 Token $\approx$ 4 个字符或 0.75 个单词。
• 对于中文：1 个汉字通常占用 1~2 个 Tokens。

如果你的文档主要是中文，建议 chunkSize 设置得稍微小一点（如 500-800），以防单个块的 Token 数超出模型限制。

#参数详解

#1. chunkSize（块大小）

定义每个文本块的最大字符数。

参考值：从 1000 开始，根据实际效果调整。

#2. chunkOverlap（重叠大小）

相邻文本块之间共享的字符数。

作用：

• 保持上下文连贯性
• 避免重要信息在边界被切断
• 确保同一个句子不会分散到多个块

参考值：chunkSize 的 10-20%

// 示例
chunkSize: 1000
chunkOverlap: 200  // 20%

// 结果：
Chunk 1: [0:1000]
Chunk 2: [800:1800]   // 800-1000 重叠
Chunk 3: [1600:2600]  // 1600-1800 重叠

为什么需要重叠？

❌ 无重叠：
Chunk 1: "...公司的毛利率为"
Chunk 2: "43.5%，相比去年下降了..."

→ 查询"毛利率是多少？"时，Chunk 1 信息不完整

✅ 有重叠：
Chunk 1: "...公司的毛利率为 43.5%，相比去年..."
Chunk 2: "毛利率为 43.5%，相比去年下降了 250 个基点..."

→ 两个块都包含完整信息

#3. separators（分隔符列表）

控制文本如何被分割。默认值：["\n\n", "\n", " ", ""]

自定义示例：

// 针对 Markdown 的分割器
const markdownSplitter = new RecursiveCharacterTextSplitter({
  chunkSize: 1000,
  chunkOverlap: 200,
  separators: [
    "\n## ",      // 二级标题
    "\n### ",     // 三级标题
    "\n\n",       // 段落
    "\n",         // 行
    " ",          // 词
    ""            // 字符
  ],
});

#递归分割的优势

为什么叫“递归”？简单说就是不死板。

它不会一上来就暴力地按 1000 字切一刀。它会先试着用“双换行符”（段落）来切。如果切完的一段还是太长，它会再进到这一段里，用“单换行符”（句子）继续切。

这种方式最大程度地保留了文本的语义结构，不会莫名其妙地把一句话切成两半。

让我们看一个具体的例子：

原始文本：

第一段。

第二段。

第三段。第四段。第五段。

使用 RecursiveCharacterTextSplitter（chunkSize=20）：

尝试 "\n\n" 分割：
✅ ["第一段。\n\n第二段。\n\n第三段。第四段。第五段。"]

"第一段。" 太短，继续分割

尝试 "\n" 分割：
✅ ["第一段。\n\n第二段。\n\n第三段。", "第四段。", "第五段。"]

"第一段。\n\n第二段。\n\n第三段。" 仍然太长

尝试 " " 分割：
✅ ["第一段。\n\n第二段。", "第三段。", "第四段。", "第五段。"]

其他分割器（如简单的字符分割）：

❌ ["第一段。\n\n第二段。\n\n第", "三段。第四段。第五段。"]
→ 在"第"字处截断，破坏了语义

结论：除非你有非常特殊的格式需求（比如代码文件用 CodeTextSplitter，Markdown 用 MarkdownTextSplitter），否则无脑选 RecursiveCharacterTextSplitter 就对了。

#实战：加载与分割

现在，我们将把学到的知识应用到代码中。我们将创建一个完整的 RAG 入口文件 src/rag/index.ts，并在其中实现文档的加载和分割。

#完整代码实现

编辑 src/rag/index.ts：

import { PDFLoader } from '@langchain/community/document_loaders/fs/pdf';
import { RecursiveCharacterTextSplitter } from '@langchain/textsplitters';
import path from 'path';
import { fileURLToPath } from 'url';
import 'dotenv/config';

// 1. 设置路径
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
const pdfPath = path.join(__dirname, 'data', 'nke-10k-2023.pdf');

// 2. 加载 PDF
console.log("📄 正在加载文档...");
const loader = new PDFLoader(pdfPath);
const docs = await loader.load();
console.log(`✅ 加载完成，共 ${docs.length} 页`);

// 3. 分割文本
console.log("✂️  正在分割文档...");
const textSplitter = new RecursiveCharacterTextSplitter({
  chunkSize: 1000,
  chunkOverlap: 200,
});

const allSplits = await textSplitter.splitDocuments(docs);
console.log(`✅ 分割完成，共生成 ${allSplits.length} 个文本块`);

// 打印第一个文本块看看效果
console.log("\n🔍 第一个文本块示例：");
console.log(allSplits[0].pageContent.slice(0, 200) + "...");
console.log("\n元数据：", allSplits[0].metadata);

#运行代码

pnpm rag

你将看到类似以下的输出，证明文档已经成功加载并被分割成了更小的块，为后续的向量化做好了准备。

📄 正在加载文档...
✅ 加载完成，共 107 页
✂️  正在分割文档...
✅ 分割完成，共生成 514 个文本块

🔍 第一个文本块示例：
Table of Contents
UNITED STATES
SECURITIES AND EXCHANGE COMMISSION...

元数据： { source: '.../src/rag/data/nke-10k-2023.pdf', pdf: { ... }, loc: { pageNumber: 1 } }

#经验之谈：参数怎么调？

很多同学问 chunkSize 和 chunkOverlap 到底该设多少？这里分享一些我的实战经验：

1. 默认起手式：chunkSize: 1000, chunkOverlap: 200。这个配置在大多数通用文档（如 PDF 报告、文章）上表现都很稳。
2. 中文环境：如果你的文档全是中文，建议适当调小 chunkSize（比如 500-800）。因为中文的信息密度比英文大，同样的字符数，中文包含的语义更多，太长了容易让 Embedding 模型“消化不良”。
3. 重叠的重要性：chunkOverlap 千万别设为 0。保持 10%-20% 的重叠能有效防止一句话被切成两半，导致语义丢失。
4. 特殊场景：问答对拆分：如果你处理的是 FAQ 文档（问答对），普通的按长度切分可能会把问题和答案切开。这时候可以考虑预处理文档，把每个“问题+答案”合并成一行，或者使用自定义分隔符（如 Q:）来确保它们始终在同一个 chunk 里。
5. 调试技巧：不要迷信理论值。最好的办法是像上面代码那样，打印出前几个 chunk 看看。如果发现经常有半截句子，就调大 overlap；如果发现包含太多无关废话，就调小 chunkSize。

#本文源码

示例代码已上传至github： https://github.com/Colin3191/langchain-demo

#欢迎来到我的博客

大家好！欢迎来到我的个人博客。

#关于这个博客

这个博客使用 Rspress 构建，是一个基于 Rust 的静态站点生成器。我选择它的原因包括：

• 快速构建：基于 Rust 的构建工具链，提供极快的编译速度
• MDX 支持：可以在 Markdown 中使用 React 组件
• 全文搜索：内置全文搜索功能
• 现代化设计：支持暗色主题，响应式设计

#博客内容

在这里你可以找到：

• 技术文章和教程
• 个人学习笔记
• 项目经验分享
• 生活感悟