Docpad曾是Node.js生态中颇受欢迎的静态站点生成器，依靠CoffeeScript和Eco模板引擎赢得了早期一批用户。但随着时间推移，Docpad的维护频率明显下降，插件生态逐渐停滞，而Next.js凭借React组件化能力、混合渲染模式和活跃的社区支持，成为静态站点现代化的首选方案之一。本文将从框架差异、迁移步骤和部署注意事项三个层面，完整讲解如何把一个Docpad站点平滑升级到Next.js。
一、Docpad与Next.js的核心差异
在动手迁移之前，理解两个框架在设计哲学上的区别非常重要。Docpad是一个典型的文件驱动型生成器，开发者按照约定把文件放进src/documents、src/files等目录，Docpad会自动扫描并生成对应的静态页面，数据则通过docpad.coffee配置文件和meta数据头部注入模板。
Next.js则是组件驱动的应用框架。页面由React组件构成，路由由pages或app目录下的文件结构自动映射，数据获取可以在构建时通过getStaticProps完成，也可以在请求时通过getServerSideProps处理。这种差异决定了迁移不是简单的文件搬运，而是需要把模板逻辑重写为组件逻辑。
具体来看三个关键差异点。第一，模板引擎：Docpad使用Eco或Jade模板，语法接近嵌入式脚本，而Next.js使用JSX，逻辑和视图天然融合在一个组件内。第二，数据层：Docpad的collections查询依赖@getFilesAt等API，Next.js则通过文件系统读取和前端的getStaticPaths配合。第三，渲染时机：Docpad全部在构建时生成，Next.js支持SSG、SSR、ISR多种模式并存，为后续功能扩展留出空间。
二、目录结构重组与页面组件改写
迁移的第一步是规划新项目的目录结构。假设原Docpad项目的文章存放在src/documents/posts目录下，每个文件头部带有meta信息。在Next.js中，推荐把这些Markdown文件移到项目根目录的content/posts目录，与代码目录分离，便于后续接入CMS。
接下来处理页面改写。以文章列表页为例，Docpad中的Eco模板大致是这样的：
<% for post in @getFilesAt('posts').findAll({isPublished:true}).toJSON(): %>
<h2><a href="<%= post.url %>"><%= post.title %></a></h2>
<% end %>改写为Next.js时，需要在构建阶段读取所有Markdown文件并解析meta头部，然后渲染成React组件：
import fs from 'fs';
import path from 'path';
import matter from 'gray-matter';
export default function Posts({ posts }) {
return (
<div>
{posts.map((post) => (
<h2 key={post.slug}>
<a href={`/posts/${post.slug}`}>{post.title}</a>
<h2>
))}
<div>
);
}
export async function getStaticProps() {
const dir = path.join(process.cwd(), 'content/posts');
const files = fs.readdirSync(dir);
const posts = files.map((file) => {
const raw = fs.readFileSync(path.join(dir, file), 'utf8');
const { data } = matter(raw);
return { slug: file.replace('.md', ''), ...data };
});
return { props: { posts } };
}这里用到了gray-matter库来解析YAML格式的meta头部，它正好对应Docpad文档顶部的元数据写法，迁移时meta字段基本可以原样保留。注意这个组件只负责列表展示，数据获取逻辑全部收敛到getStaticProps中，这正是Next.js与Docpad在架构上最大的不同。
文章详情页需要配合getStaticPaths生成动态路由，把每篇文章的slug作为路径参数传入。这样做的好处是所有页面在构建时预渲染为纯静态HTML，与Docpad的产出物完全一致，同时保留了按需扩展动态内容的能力。
export async function getStaticPaths() {
const files = fs.readdirSync(path.join(process.cwd(), 'content/posts'));
return {
paths: files.map((file) => ({ params: { slug: file.replace('.md', '') } })),
fallback: false,
};
}三、静态资源、布局与部署注意事项
Docpad项目中src/files目录存放的图片、CSS、字体等静态资源，在Next.js中统一放入public目录，引用路径保持不变即可。样式方面，如果原来用的是Stylus或Less，可以直接沿用对应的webpack配置，也可以趁机迁移到CSS Modules或Tailwind CSS，后者与React组件的配合更为自然。
布局与公共组件的转换同样重要。Docpad的default布局通常包含页头、页脚和导航，迁移时把它拆分为Layout组件和若干小组件，通过props或Context传递页面标题等信息。这样每个页面组件只需关注自身内容，复用性和可测试性都会显著提升。
部署环节需要注意构建命令的差异。Docpad执行docpad generate产出out目录，Next.js则执行next build产出静态导出目录。如果站点完全静态，可以在next.config.js中开启导出模式：
// next.config.js
module.exports = {
output: 'export',
images: { unoptimized: true },
};开启后执行next build会生成out目录，包含全部静态HTML和资源文件，可以直接托管到Nginx、对象存储或任何静态服务器，部署方式与Docpad的产出物无缝衔接。
最后提醒几个常见坑点。第一，Docpad中带有分页的列表页需要用getStaticPaths手动展开所有分页路径，不能遗漏。第二，RSS订阅、sitemap等功能原来依赖Docpad插件，迁移后需要改用next/feed和next-sitemap等社区包实现。第三，如果部分页面依赖运行时数据，可保留SSG为主的架构，个别路由改用getServerSideProps，Next.js允许两种模式混用，这是相比Docpad全静态模式的一大优势。
整体而言，Docpad到Next.js的迁移工作量主要集中在模板改写和数据获取逻辑重构上，Markdown内容和meta数据几乎可以无损搬移。完成迁移后，站点不仅能继续以纯静态方式部署，还获得了React生态的组件化能力和更灵活的渲染选项，是一次值得投入的升级。