本地开发

一、环境准备

1.1 创建 Next.js 项目

打开cmd命令行。输入：

pnpm create next-app@latest Blog --typescript --tailwind --eslint --app

自定义路径：命令中的 Blog 是项目名称（即创建的项目文件夹名），你可以根据实际需要将其改为任意名称，例如 my-blog、./docs（相对路径）等。

在D:\blog目录下新建 Next.js 项目，则可以输入pnpm create next-app@latest "D:\blog" --typescript --tailwind --eslint --app

你已经在D:\blog目录下启动了cmd命令行，则可以输入pnpm create next-app@latest .\ --typescript --tailwind --eslint --app

最后一行会显示 Success! Created blog at D:\blog。

提示 pnpm: command not found，请先安装 pnpm（安装命令：npm install -g pnpm）。

1.2 安装 Fumadocs 核心依赖

pnpm add fumadocs-mdx fumadocs-core @types/mdx

此时，你会看到下面的提示样例：

Warning
  Ignored build scripts: esbuild@0.28.0.
  Run "pnpm approve-builds" to pick which dependencies should be allowed to run scripts.

上述警告是正常的，不影响后续使用。esbuild 的构建脚本被忽略仅表示 pnpm 的默认安全策略，无需额外操作。

Done in (构建耗时)s using pnpm v(版本)，无红色 error。

1.3 创建 `source.config.ts`

在项目根目录 D:\blog 下创建一个新文件 source.config.ts，内容如下：

import { defineDocs, defineConfig } from 'fumadocs-mdx/config';

export const docs = defineDocs({
  dir: 'content/docs',
});

export default defineConfig();

验证：在 cmd 中执行 type source.config.ts 应显示上述内容。

1.4 修改 `Next.js` 配置文件

Next.js 默认生成的是 next.config.ts（TypeScript 版本），但 Fumadocs 需要 ES Module 格式的 .mjs 文件。请按以下步骤操作：

1.4.1 重命名 next.config.ts 文件为 next.config.mjs ;

1.4.2 编辑 next.config.mjs，将其全部内容替换为：

import { createMDX } from 'fumadocs-mdx/next';

/\*\* @type {import('next').NextConfig} \*/
const config = {
  reactStrictMode: true,
};

const withMDX = createMDX({});
export default withMDX(config);

验证：在 cmd 中执行 type next.config.mjs 应显示上述内容。

文件名仍是 .ts，请返回步骤 1 重命名。

SyntaxError: Cannot use import statement outside a module 文件扩展名必须是 .mjs，不是 .js。

1.5 配置 `tsconfig.json` 路径别名

打开项目根目录下的 tsconfig.json，在 compilerOptions 中添加以下 paths 配置：

"paths": {
  "@/*": ["./*"],
  "collections/*": ["./.source/*"]
}

完成后执行 pnpm dev 进行构建。

之后你会看到类似输出：

⚠ Port 3000 is in use by process 1432, using available port 3001 instead.
▲ Next.js 16.2.4 (Turbopack)
- Local:         http://localhost:3000
- Network:       http://192.168.XX.XXX:3000
✓ Ready in 483ms
[MDX] generated files in 11.158300000000054ms
[MDX] started dev server

在浏览器中打开 http://localhost:3000 ，你就能看到 Next.js 构建成功的页面。

注意：collections/* 是 Fumadocs MDX 构建后生成的虚拟模块路径。首次运行 pnpm dev 时会自动生成 .source 目录，此后 TypeScript 就能正确识别。

验证：保存文件后，VS Code 中不应出现红色波浪线。如果仍有报错，请先执行一次 pnpm dev（即使会报其他错误），让 .source 文件夹生成。

二、创建文档源文件

2.1 创建索引

首先在根目录下创建 lib 文件夹，然后在其中新建 source.ts 文件。

使用 VS Code 或记事本手动创建 lib/source.ts，复制以下代码：

mkdir -p lib
cat > lib/source.ts << 'EOF'
import { docs } from 'collections/server';
import { loader } from 'fumadocs-core/source';

export const source = loader({
  baseUrl: '/docs',
  source: docs.toFumadocsSource(),
});
EOF

验证：在 cmd 中执行 type lib\source.ts ，输出如上，无语法错误提示。

2.2 创建测试文档

在根目录下创建 content 文件夹。然后继续创建 docs文件夹，并在其中新建 index.mdx 文件。

我们手动创建 content\docs\index.mdx。

---
title: Hello World
---

## 你好！

Hello World

注意：--- 行前后不能有空格。

三、安装 UI 并配置样式与布局

3.1 安装 UI 包

pnpm add fumadocs-ui

如果之前已经安装过 fumadocs-core 和 @types/mdx，这一步只需要添加 fumadocs-ui。

依赖安装完成，node_modules 中存在 fumadocs-ui。

3.2 修改全局样式

用 VS Code 或记事本打开 app/globals.css 文件，清空文件并写入下述，然后保存退出。

@import 'tailwindcss';
@import 'fumadocs-ui/css/neutral.css';
@import 'fumadocs-ui/css/preset.css';

3.3 修改根布局

用 VS Code 或记事本打开 app/layout.tsx 文件，清空文件并写入下述，然后保存退出。

import './globals.css';
import { RootProvider } from 'fumadocs-ui/provider';
import type { ReactNode } from 'react';

export default function Layout({ children }: { children: ReactNode }) {
  return (
    <html lang="zh-CN" suppressHydrationWarning>
      <body className="flex flex-col min-h-screen">
        <RootProvider>{children}</RootProvider>
      </body>
    </html>
  );
}

注意：RootProvider 从 'fumadocs-ui/provider' 导入，不是 'fumadocs-ui/provider/next'。

验证：文件顶部有 import './globals.css'，<body> 有正确的 className。

3.4 创建共享布局选项

打开 lib 文件夹，用 VS Code 或记事本创建 layout.shared.tsx 文件，然后保存退出。

import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';

export function baseOptions(): BaseLayoutProps {
  return {
    nav: {
      title: '我的 Blog',
    },
  };
}

3.5 创建 MDX 组件文件

在根目录新建 mdx-components.tsx，内容如下：

import defaultMdxComponents from 'fumadocs-ui/mdx';
import type { MDXComponents } from 'mdx/types';

export function getMDXComponents(components?: MDXComponents): MDXComponents {
  return {
    ...defaultMdxComponents,
    ...components,
  };
}

验证：在 cmd 中执行 type mdx-components.tsx 应显示上述内容。

不要写成 useMDXComponents，否则后续页面会找不到组件。

3.6 创建文档布局

打开 app 文件夹，新建 docs 文件夹，在 docs 文件夹内新建文件 layout.tsx 。

import { source } from '@/lib/source';
import { DocsLayout } from 'fumadocs-ui/layouts/docs';
import { baseOptions } from '@/lib/layout.shared';

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <DocsLayout tree={source.pageTree} {...baseOptions()}>
      {children}
    </DocsLayout>
  );
}

注意：使用 source.pageTree（属性），不是 source.getPageTree()。

验证：source 导入无报错（运行 pnpm dev 时自动生成 .source 文件夹）。

3.7 创建文档页面

该路径是一个可选 catch-all 路由，文件夹名必须为 [[...slug]]（两个方括号加三个点）。

打开 app/docs 文件夹，新建文件夹 [[...slug]] ，然后在该文件夹内新建文件 page.tsx。

import { source } from '@/lib/source';
import {
  DocsBody,
  DocsDescription,
  DocsPage,
  DocsTitle,
} from 'fumadocs-ui/page';
import { notFound } from 'next/navigation';
import { getMDXComponents } from '@/mdx-components';
import type { Metadata } from 'next';

type PageProps = {
  params: Promise<{ slug?: string[] }>;
};

export default async function Page(props: PageProps) {
  const params = await props.params;
  const page = source.getPage(params.slug);
  if (!page) notFound();

  const MDXContent = page.data.body;

  return (
    <DocsPage toc={page.data.toc} full={page.data.full}>
      <DocsTitle>{page.data.title}</DocsTitle>
      <DocsDescription>{page.data.description}</DocsDescription>
      <DocsBody>
        <MDXContent components={getMDXComponents()} />
      </DocsBody>
    </DocsPage>
  );
}

export async function generateStaticParams() {
  return source.generateParams();
}

export async function generateMetadata(props: PageProps): Promise<Metadata> {
  const params = await props.params;
  const page = source.getPage(params.slug);
  if (!page) notFound();

  return {
    title: page.data.title,
    description: page.data.description,
  };
}

从 @/mdx-components 导入 getMDXComponents（与根目录的文件对应）。

MDXContent 是一个组件，应直接使用 <MDXContent components={...} /> 。

3.8 创建搜索 API

打开 app 文件夹，新建文件夹 api ，然后在该文件夹内新建文件夹 search，最后在 search 文件夹内新建文件 route.ts。

import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';

export const { GET } = createFromSource(source, {
  language: 'chinese', // 或 'english'
});

验证：执行 pnpm dev 后访问 /api/search 应返回 JSON（空结果）。

四、本地运行测试

pnpm dev

终端显示 Ready in XXXms，访问 http://localhost:3000/docs 看到 "Hello World" 和文档布局（有侧边栏、标题）。

检查 app/layout.tsx 是否导入 ./globals.css，并执行 Ctrl+Shift+R 硬刷新。

检查 app/docs/[[...slug]]/page.tsx 路径是否正确，以及 content/docs/index.mdx 是否存在。

五、自定义首页

创建 app/page.tsx（示例）：

import Link from 'next/link';

export default function HomePage() {
  return (
    <div className="container mx-auto px-4 py-12">
      <h1 className="text-4xl font-bold">欢迎来到我的网站</h1>
      <p className="mt-4 text-lg">这是一个完整的网站首页。</p>
      <Link href="/docs" className="mt-6 inline-block rounded bg-blue-600 px-4 py-2 text-white">
        查看文档
      </Link>
    </div>
  );
}

验证：访问 http://localhost:3000/ 看到自定义内容，而非 Next.js 默认页。

声明

作者：圣堂之魂；发布于：2026-05-04；许可协议：CC BY-NC-SA 4.0

本地开发

什么是 Fumadocs？

需要准备什么？

软件支持？

声明

本页目录