程序员の黑暗兵法：用Nextra模板一天搞出爆款文档站！

小数没有点
646 阅读8分钟

image.png

image.png

不好意思，标题党了，各位看官大佬帮忙看下标题行不行

最近发现一个超火的 "面试宝典" 网站，正是用我这个模板nextjs-nextra-starter开发的！真是太快了，一下就火起来了，赶紧借这个机会蹭一波热度～🏄‍♂️

"面试宝典"，是个"免费且深入的八股文网站"。看到自己的模板被用起来，内心很平静(bushi)！真心感谢这位大佬的支持，看到自己的模板被用到这样的项目里，真的挺开心的。虽然…有点小遗憾的是，没看到来源标注一下，哈哈，不管了，硬蹭一波流量也挺不错的！

（希望能够蹭到吧，希望大佬也帮我推广支持下，此处手动 @ 这位大佬 ）🤣

前言

好了，不多说，接下来给大家简单介绍一下这个模板的核心功能吧！

作为一名前端工程师，我一直在寻找能够同时兼顾开发效率和用户体验的技术栈。在过去的几个月中，我深入研究了 Next.js 和 Nextra 的结合使用，并基于这两个强大的框架打造了一个开源的文档站点模板。

今天和大家分享这个项目的技术细节和使用体验，希望能为正在寻找类似解决方案的开发者提供一些参考。

💡 特别提醒：本项目仍处于早期阶段，作为模板提供基础功能，但具体内容仍需自行扩展。如有问题或建议，欢迎在 GitHub 提交 Issue 或 PR。🙏 感谢您的每一份反馈！

让技术为内容赋能 ✨

在经历了多次搭建技术文档和知识库的过程，包括将 Tailwind CSS v3 和 Nextra v3 均重构到 v4 版本，我深刻体会到 Next.js + Nextra 这对组合的威力：

Markdown 零成本写作、智能路由自动生成、深度主题定制——这些特性使其成为内容优先型网站的首选架构。

但每次从零开始配置 SEO 优化、代码高亮、响应式布局等细节，仍然需要数小时。于是我决定将最佳实践沉淀为这套 nextjs-nextra-starter 脚手架模板，让你能：

✅ 5 分钟极速初始化 - 通过 create-next-app 直接生成完整项目
✅ 零配置写作体验 - 专注用 Markdown 创作内容，自动生成导航与交互式组件
✅ 企业级功能预置 - 自适应暗色模式、多语言支持、SEO 元标签优化
✅ 模块化拓展能力 - 内置组件可替换，支持自定义布局与主题扩展

🚀 适用场景

  • 技术文档中心（如 API 手册、SDK 指南）
  • 结构化知识库（如面试题库、产品百科）
  • 个人技术博客 / 周刊
  • 开源项目文档站点

为什么选择 Next.js + Nextra?

在开始正式介绍项目前，我想先说明为什么会选择 Next.js + Nextra 这个组合：

  • ⚡️ Next.js + TypeScript: 高效的 React 框架和类型安全支持
  • 🎨 Tailwind CSS (v4) : 原子化 CSS, 快速构建自定义、响应式界面 UI
  • 🧩 Shadcn UI: 高度可定制的 UI 组件集合，无需安装额外依赖
  • 📚 Nextra v4: 基于 Next.js 的静态站点生成器，专为文档而优化
  • 🛠️ ESLint: 统一编码风格和最佳实践
  • ⛅ 轻量化设计: 精简项目设置，专注于内容编写

这些技术的组合不仅适用于构建文档网站，也同样适合开发博客、营销页面等各类内容型网站

项目简介

nextjs-nextra-starter 是一个轻量、高效的 Next.js + Nextra 模板，集成了 React 19、Next.js、Nextra v4、TypeScript、Tailwind CSS v4 和 Shadcn UI 等最新技术

image.png

该模板旨在帮助开发者快速启动一个文档站点项目，无需花费大量时间在项目配置上。你可以直接关注内容创作，而将技术细节交给模板处理。

最新升级亮点

最近，我对项目进行了全面升级，引入了 Tailwind CSS v4 和 Nextra v4 的最新特性。下面来详细介绍这些升级带来的变化，详细的升级亮点也可以在 在线文档 中查看到 ~

Nextra v4 重大更新

Nextra v4 带来了许多激动人心的改进：

  • 🚀 App Router 支持：全面切换至 Next.js App Router，淘汰 Pages Router，支持最新的 Metadata API
  • ⚡ 更快的页面加载：优化后的打包体积与性能，使网站响应更迅速
  • 🔍 全新搜索引擎：基于 Rust 的 Pagefind 提供更精准、更高效的搜索体验
  • 🏎️ Turbopack 支持：改进开发体验，解决长期的社区需求
  • 🌍 RSC + i18n：增强国际化支持，使多语言网站开发更加便捷
  • 📱 更好的移动端适配：针对小屏幕设备优化显示效果和交互体验

Tailwind CSS v4 性能飞跃

Tailwind CSS v4 同样带来了革命性的提升：

  • 🚀 全新高性能引擎：完整构建速度提升最多 5 倍，增量构建速度提升超过 100 倍
  • 💎 现代 Web 设计：基于前沿的 CSS 特性构建，如层叠层（cascade layers）、@property 自定义属性和 color-mix()
  • 🎯 简化安装过程：更少的依赖，零配置，只需在 CSS 文件中添加一行代码
  • 🔍 自动内容检测：自动发现所有模板文件，无需繁琐配置

这些更新不仅提升了开发效率，也极大改善了最终用户的体验。

💻 快速上手

如果你想快速体验这个模板，可以按照以下步骤进行，当然是需要准备一些些前置条件的：

前置条件

  • React 19.x
  • Node >= 18.12.x
  • Pnpm 9.x
  • VS Code 插件 dbaeumer.vscode-eslint >= v3.0.5 (pre-release)

安装和运行

  1. 克隆本仓库到本地
git clone https://github.com/pdsuwwz/nextjs-nextra-starter.git
cd nextjs-nextra-starter

不想克隆的话，直接在仓库页面右上角点选 "Use this template" 也可以：

image.png

  1. 安装依赖
pnpm i
  1. 本地开发
pnpm dev
  1. 本地运行后直接在浏览器中访问 http://localhost:8000 即可

image.png

使用 Shadcn UI 组件

这个模板已经集成了 Shadcn UI，你可以通过以下简单步骤添加和使用组件：

  1. 使用 Shadcn CLI 添加组件:
pnpm dlx shadcn@latest add <组件名>

例如，添加 Alert 组件:

pnpm dlx shadcn@latest add alert
  1. 在代码中使用组件
import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert'

export default function Home() {
  return (
    <Alert>
      <AlertTitle>Heads up!</AlertTitle>
      <AlertDescription>
        You can add components and dependencies to your app using the cli.
      </AlertDescription>
    </Alert>
  )
}

深入技术细节

接下来，我想分享一些这个模板在实现过程中的技术细节和经验：

1. Nextra 的国际化支持

Nextra v4 对国际化支持做了很大改进。在我的模板中，你可以看到中英文切换的完美实现，但如果 tsx 也想在 mdx 中复用的话，则需要额外处理，为此本项目封装了一个 i18n Hooks：

// Nextra 配置中的国际化设置
export default {
  i18n: [
    { locale: 'en', text: 'English' },
    { locale: 'zh', text: '中文' },
  ],
  defaultLocale: 'en'
}

i18n Hooks 在这里面，感兴趣的可以看下源代码：

image.png

这使得创建多语言网站变得异常简单，只需在 /content 目录下创建对应的语言文件夹即可。

2. Tailwind CSS + Shadcn UI 的组合威力

Tailwind CSS 和 Shadcn UI 的组合是这个模板的一大亮点。Tailwind 提供了原子化的 CSS 能力，而 Shadcn UI 则提供了一系列高质量的组件实现：

// 一个使用 Tailwind + Shadcn UI 的导航栏示例
<nav className="flex items-center space-x-4 lg:space-x-6">
  <Button variant="ghost" className="text-sm font-medium transition-colors">
    首页
  </Button>
  <DropdownMenu>
    <DropdownMenuTrigger asChild>
      <Button variant="ghost" className="text-sm font-medium">
        更多 <ChevronDown className="ml-1 h-4 w-4" />
      </Button>
    </DropdownMenuTrigger>
    <DropdownMenuContent>
      <DropdownMenuItem>项目1</DropdownMenuItem>
      <DropdownMenuItem>项目2</DropdownMenuItem>
    </DropdownMenuContent>
  </DropdownMenu>
</nav>

🌟 参与共建

自从这个项目发布以来，我收到了一些开发者的反馈。特别感谢那些提交 issue 和 PR 的开发者，正是你们的参与让这个项目变得更好。

如果你也在使用这个模板，欢迎通过以下方式参与进来：

  1. 提交 Issue 分享你的项目或反馈问题
  2. 提交 Pull Request 改进模板功能或文档
  3. 在社交平台上分享你使用这个模板的体验（记得标注来源哦，不然我会暗自神伤的😢）

未来计划

对于这个项目，我有几点未来发展计划：

  1. 添加更多实用组件和示例代码
  2. 优化移动端体验
  3. 提供更多主题定制选项
  4. 探索 Next.js Server Components 更多的可能性 ~ ~

并且我也会持续关注 Next.js 和 Nextra 的最新发展，及时将新特性集成到模板中。

（先暂时挖这几个坑吧...

🌹支持

如果你觉得这个项目有帮助，或喜欢我的工作，欢迎点击项目的右上角的 ⭐️ Star 按钮进行支持！

每一个星标都是对我最大的鼓励，就像有人使用你的开源项目时给你一个明确的引用和致谢一样，真的非常感激！😉

最后

Next.js + Nextra 的组合为开发文档站点和内容型网站提供了极佳的解决方案。

我开发的这套nextjs-nextra-starter模板则进一步简化了开发流程，让开发者能够专注于内容创作而非技术细节。

无论你是想搭建一个技术文档站点、个人博客，还是类似 "面试宝典" 那样的知识库网站，这个模板都能帮你快速起步并取得出色的用户体验。

avatar
文章
阅读
粉丝