挑战：Next.js 13 静态页面与本地数据访问
在 Next.js 13 的 App Router 架构中，构建一个从本地文件（如 Markdown 文章）生成静态页面的博客系统是常见需求。然而，当需要为这些文章列表添加客户端交互功能（如搜索、过滤）时，会遇到一些挑战：
- fs 模块的限制：Node.js 的 fs 模块用于文件系统操作，只能在服务器端运行。在需要使用 useState、useEffect 等 React Hooks 的客户端组件中，直接使用 fs 会导致运行时错误。
- getStaticProps 的废弃：在 App Router 中，getStaticProps 等数据获取方法已被废弃，取而代之的是服务器组件中的异步数据获取能力。
- 本地文件 fetch API 的局限：Next.js 官方文档推荐使用 fetch API 进行数据获取，但 fetch 主要用于网络资源，无法直接读取本地文件系统中的文件。
- 静态站点生成（SSG）的需求：对于部署到 S3/CloudFront 等静态托管服务的站点，所有页面内容需要在构建时完全生成。
这些限制使得在客户端组件中直接访问本地 Markdown 文件变得复杂，而将 fs 操作与客户端交互结合是核心问题。
Next.js 13 App Router 的解决方案：服务器组件预处理数据
解决此问题的关键在于充分利用 Next.js 13 App Router 的服务器组件和客户端组件分离的架构。基本思路是：
- 在服务器组件中执行 fs 操作：利用服务器组件的特性，在构建时（或渲染时）安全地使用 fs 模块读取本地 Markdown 文件。
- 处理并转换数据：将读取到的 Markdown 内容进行解析（例如使用 gray-matter 提取元数据，使用 remark 转换为 HTML）。
- 将处理后的数据传递给客户端组件：服务器组件将这些处理好的数据作为 props 传递给需要客户端交互的子组件。
- 客户端组件实现交互：客户端组件接收到数据后，可以自由地使用 React Hooks 实现搜索、过滤等功能，而无需关心数据来源的底层文件系统操作。
这种模式确保了 fs 操作只在服务器端进行，同时允许客户端组件获得所需数据并提供丰富的用户体验。
实现步骤与示例代码
我们将通过一个博客文章列表的例子来演示这一解决方案。
1. 定义服务器端数据获取工具函数 (lib/posts.ts)
首先，创建一个包含 fs 操作的工具文件。这些函数将在服务器组件中被调用。
// lib/posts.ts
import fs from 'fs';
import path from 'path';
import matter from 'gray-matter';
import { remark } from 'remark';
import html from 'remark-html';
export interface BlogPost {
id: string;
title: string;
date: string;
tags?: string[];
}
export interface BlogPostWithHTML extends BlogPost {
contentHtml: string;
}
const postsDirectory = path.join(process.cwd(), 'public/posts'); // 假设 Markdown 文件存放在 public/posts
/**
* 获取所有文章的ID
* @returns 包含所有文章ID的数组
*/
export function getAllPostIds() {
const fileNames = fs.readdirSync(postsDirectory);
return fileNames.map((fileName) => {
return {
params: {
id: fileName.replace(/\.md$/, ''),
},
};
});
}
/**
* 根据ID获取单篇文章数据（包含HTML内容）
* @param id 文章ID
* @returns 包含文章元数据和HTML内容的BlogPostWithHTML对象
*/
export async function getPostData(id: string): Promise {
const fullPath = path.join(postsDirectory, `${id}.md`);
const fileContents = fs.readFileSync(fullPath, 'utf8');
// 使用 gray-matter 解析文章元数据
const matterResult = matter(fileContents);
// 使用 remark 将 Markdown 内容转换为 HTML
const processedContent = await remark().use(html).process(matterResult.content);
const contentHtml = processedContent.toString();
const blogPostWithHTML: BlogPostWithHTML = {
id,
title: matterResult.data.title,
date: matterResult.data.date,
tags: matterResult.data.tags || [],
contentHtml,
};
return blogPostWithHTML;
}
/**
* 获取所有排序后的文章摘要数据（不包含完整HTML内容，除非列表需要）
* @returns 包含所有文章元数据的数组，按日期降序排列
*/
export async function getSortedPostsData(): Promise {
const fileNames = fs.readdirSync(postsDirectory);
const allPostsData = await Promise.all(
fileNames.map(async (fileName) => {
const id = fileName.replace(/\.md$/, '');
const fullPath = path.join(postsDirectory, fileName);
const fileContents = fs.readFileSync(fullPath, 'utf8');
const matterResult = matter(fileContents);
return {
id,
title: matterResult.data.title,
date: matterResult.data.date,
tags: matterResult.data.tags || [],
};
})
);
// 按日期降序排序
return allPostsData.sort((a, b) => {
if (a.date < b.date) {
return 1;
} else {
return -1;
}
});
} 2. 创建服务器组件获取数据并传递 (app/blog/page.tsx)
这个服务器组件负责调用 lib/posts.ts 中的函数，获取所有文章数据，然后将数据传递给客户端组件。
// app/blog/page.tsx (这是一个服务器组件)
import { getSortedPostsData, BlogPost } from '@/lib/posts'; // 确保路径正确
import BlogListClient from './components/BlogListClient'; // 客户端组件
export default async function BlogPage() {
const allPostsData: BlogPost[] = await getSortedPostsData();
return (
博客文章
{/* 将所有文章数据作为 props 传递给客户端组件 */}
3. 创建客户端组件实现搜索和过滤 (app/blog/components/BlogListClient.tsx)
这个客户端组件接收服务器组件传递的数据，并实现搜索和过滤的交互逻辑。
// app/blog/components/BlogListClient.tsx
'use client'; // 标记为客户端组件
import React, { useState, useMemo } from 'react';
import Link from 'next/link';
import { BlogPost } from '@/lib/posts'; // 确保路径正确
interface BlogListClientProps {
posts: BlogPost[];
}
export default function BlogListClient({ posts }: BlogListClientProps) {
const [searchTerm, setSearchTerm] = useState('');
const [selectedTag, setSelectedTag] = useState(null);
const filteredPosts = useMemo(() => {
let currentPosts = posts;
// 按标签过滤
if (selectedTag) {
currentPosts = currentPosts.filter(post => post.tags?.includes(selectedTag));
}
// 按搜索词过滤
if (searchTerm) {
const lowerCaseSearchTerm = searchTerm.toLowerCase();
currentPosts = currentPosts.filter(
(post) =>
post.title.toLowerCase().includes(lowerCaseSearchTerm) ||
post.id.toLowerCase().includes(lowerCaseSearchTerm)
);
}
return currentPosts;
}, [posts, searchTerm, selectedTag]);
// 获取所有不重复的标签
const allTags = useMemo(() => {
const tags = new Set();
posts.forEach(post => post.tags?.forEach(tag => tags.add(tag)));
return Array.from(tags);
}, [posts]);
return (
setSearchTerm(e.target.value)}
/>
{filteredPosts.length > 0 ? (
filteredPosts.map(({ id, title, date, tags }) => (
-
{title}
{date}
{tags && tags.length > 0 && (
{tags.map(tag => (
{tag}
))}
)}
))
) : (
没有找到匹配的文章。
)}
);
} 4. 创建动态路由页面 (app/blog/[id]/page.tsx)
对于单个文章页面，仍然可以通过服务器组件直接读取和渲染，无需客户端组件参与 fs 操作。
// app/blog/[id]/page.tsx (这是一个服务器组件)
import { getPostData, getAllPostIds, BlogPostWithHTML } from '@/lib/posts';
import Link from 'next/link';
// generateStaticParams 用于在构建时生成所有可能的 [id] 路径
export async function generateStaticParams() {
const paths = getAllPostIds();
return paths;
}
export default async function PostPage({ params }: { params: { id: string } }) {
const postData: BlogPostWithHTML = await getPostData(params.id);
return (
{postData.title}
发布日期: {postData.date}
{postData.tags && postData.tags.length > 0 && (
{postData.tags.map(tag => (
{tag}
))}
)}
← 返回博客列表
);
}注意事项与权衡
- 数据量与性能：这种方法在服务器组件中一次性读取并处理了所有 Markdown 文件。对于文章数量较少（如本例中的“只有两篇”）的博客，这不是问题。但如果文章数量非常庞大，这可能导致构建时间增加和传递给客户端组件的 props 数据量过大，从而影响页面加载性能。在这种情况下，可能需要考虑分页加载或更高级的缓存策略。
- 静态生成：此方案完全支持静态站点生成（SSG）。getSortedPostsData 和 getPostData 在构建时运行，生成所有页面的 HTML 文件，非常适合部署到 S3/CloudFront 等静态托管服务。
- 客户端组件的职责：客户端组件只负责 UI 渲染和交互逻辑，不涉及任何文件系统操作。这使得客户端组件更轻量、可测试性更强。
- public 目录的使用：示例中将 Markdown 文件放在 public/posts 目录下。这意味着这些文件在构建后会直接暴露在 URL 下。如果需要保护这些文件不被直接访问，可以考虑将它们放在项目根目录下的其他非 public 文件夹中（例如 _posts），并相应调整 postsDirectory 的路径。
总结
Next.js 13 App Router 为处理本地数据和客户端交互提供了强大的能力。通过将文件系统操作隔离到服务器组件中，并在构建时预处理所有必要数据，我们可以有效地将这些数据传递给客户端组件，从而实现静态页面上的复杂客户端交互功能，如搜索和过滤。这种模式既保证了构建时的性能和安全性，又提供了灵活的客户端用户体验，是构建高性能、可扩展静态站点的理想选择。
