Next.js 结合 ButterCMS 构建静态生成内容站的完整实战：cms-buttercms 示例解析-北京尧图网络

Next.js 结合 ButterCMS 构建静态生成内容站的完整实战cms-buttercms 示例解析【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js本文以 Next.js 官方仓库中的 cms-buttercms 示例为主线讲解如何用 ButterCMS 作为数据源搭建一个包含落地页、博客、分类/标签页、站内搜索的完整网站覆盖安装、环境变量配置、预览模式与 Vercel 部署全流程读完后你将掌握 Next.js Pages Router 的getStaticPaths/getStaticProps/revalidateISR在真实 CMS 集成中的落地方式并能对照 API 封装层与路由配置理解每个关键参数的作用。示例定位一个开箱即用的 CMS 驱动站点该示例的 README 将其定义为fully-functional, drop-in proof-of-concept——一个与 ButterCMS 账号完全打通的 Next.js 起步项目。它包含以下能力动态内容全集成主菜单、落地页、博客文章、分类、标签全部来自 ButterCMS 账号中的动态数据静态生成Static Generation为核心渲染策略页面在构建期/请求期由 CMS 数据预渲染内置搜索功能博客支持按关键词搜索、按分类与标签过滤自定义主题基于 Bootstrap 的完整站点主题落地页采用API 驱动的分节组件模式示例内容自动创建注册 ButterCMS 免费试用后账号后台会自动生成本示例所需的全部样例内容落地页、菜单、博客文章等无需手动造数据。从源码结构看示例采用 Pages Routerpages/目录 getInitialProps/getStaticProps/getServerSidePropspackage.json 中声明next: ^12.1.0、buttercms: ^1.2.8即该集成模式验证于 Next.js 12 时代的 Pages Router其静态生成思想在 App Router 中同样适用。目录结构总览examples/cms-buttercms/ ├── components/ │ ├── blog/ # 博客组件文章列表、文章卡片、分类侧栏、搜索框 │ ├── landing-page-sections/ # 落地页分节组件hero、features、testimonials 等 │ ├── main-menu/ # 主菜单 │ ├── _app 相关布局组件 # 页头/页脚/加载器/回顶按钮等 ├── lib/api.js # ButterCMS 客户端与全部数据获取函数核心 ├── pages/ │ ├── blog.js # 博客列表静态生成 │ ├── blog/[slug].js # 单篇文章静态生成 fallback │ ├── blog/category/[slug].js# 分类页ISRrevalidate: 1 │ ├── blog/tag/[slug].js # 标签页 │ ├── blog/search.js # 搜索结果页SSR │ ├── landing-page/[slug].js # 落地页静态生成 fallback │ ├── _app.js / _document.js │ └── missing-token.js # 未配置 API Key 时的提示页 ├── .env.local.example ├── app.json # Vercel App 清单一键部署元数据 └── next.config.js一、获取与安装示例README 提供了两条安装路径对应从零克隆与脚手架引导两种工作流。方式一克隆仓库后用 npm / Yarn 安装git clone https://github.com/ButterCMS/nextjs-starter-buttercms.git cd nextjs-starter-buttercms npm install # 或 yarn install在本地复现时等价做法是直接查看本仓库中的 examples/cms-buttercms 目录其package.json即为完整依赖清单buttercms、camelcase-keys、date-fns、bootstrap、tiny-slider、sharp等。方式二通过 Create-Next-App 引导使用npxnpm、yarn或pnpm执行 create-next-app 并指定示例名即可一键拉取该示例模板npx create-next-app --example cms-buttercms cms-buttercms-appyarn create next-app --example cms-buttercms cms-buttercms-apppnpm create next-app --example cms-buttercms cms-buttercms-app其中--example cms-buttercms对应本仓库的示例目录名cms-buttercms-app为新建的目标项目目录名。二、配置API Key、环境变量与启动Step 1. 获取 ButterCMS API Token在 ButterCMS 注册账号后后台会直接展示一个免费 API Token后续所有数据请求都依赖它。Step 2. 设置环境变量本示例通过 .env.local.example 给出环境变量模板其内容只有一行NEXT_PUBLIC_BUTTER_CMS_API_KEYyour_auth_token按 README 的操作步骤cp .env.local.example .env.local然后在.env.local中设置各变量NEXT_PUBLIC_BUTTER_CMS_API_KEY填入你的 ButterCMS API Key。变量带NEXT_PUBLIC_前缀意味着客户端代码也能读到本示例中它同时用于服务端渲染守卫见下文missing-token重定向。PREVIEW可选控制是否允许 CMS 中的草稿内容被返回。该变量在 lib/api.js 中的解析逻辑值得逐行看清const previewSetting process.env.PREVIEW; // make preview mode by default const preview previewSetting true || previewSetting undefined ? 1 : 0; try { butter Butter(process.env.NEXT_PUBLIC_BUTTER_CMS_API_KEY, preview); } catch (e) { console.log(e); }从源码可以看出预览草稿可见模式默认开启——只有显式设置PREVIEWfalse时preview才会为0PREVIEWtrue或未设置都视为开启。第二个参数preview会透传给 Butter SDK 客户端决定 API 是否返回未发布的草稿内容。Step 3. 开发模式运行注册 ButterCMS 后账号内已自动创建本示例所需的全部示例内容。运行npm install npm run dev # 或 yarn install yarn dev启动后访问http://localhost:3000即可看到完整的起步站点基于 API 组件的落地页、基于 API 的主菜单以及博客。未配置 Token 时的兜底行为值得注意的细节是示例做了缺 Key 不崩的优雅降级。next.config.js 中的redirects()会根据 Token 是否存在动态决定重定向规则redirects() { const sourcesRequiringAuthToken [ /, /landing-page/:slug*, /blog/:path*, ]; return process.env.NEXT_PUBLIC_BUTTER_CMS_API_KEY ? [ { source: /missing-token, destination: /, permanent: false, }, ] : sourcesRequiringAuthToken.map((source) ({ source: source, destination: /missing-token, permanent: false, })); },有 Token仅保留/missing-token → /的回退重定向无 Token首页、所有落地页与博客路径全部 302 到/missing-token由 pages/missing-token.js 渲染的提示页承接。同样地pages/_app.js 的MyApp.getInitialProps中只在authToken存在时才调用getMainMenu()拉取菜单否则传入空数组[]保证无 Key 时应用仍可渲染布局。三、API 封装层lib/api.js 的核心函数整个示例与 ButterCMS 的通信被集中封装在 examples/cms-buttercms/lib/api.js 中这是理解数据流的枢纽。除客户端初始化外关键函数签名如下函数作用关键参数与行为getLandingPage(slug)按 slug 获取单张落地页调用butter.page.retrieve(landing-page, slug)getLandingPages()获取全部落地页内部以defaultPageSize 100分页while 循环翻页直到next_page为空getPostsData({ page, pageSize, tag, category })文章列表默认pageSize 10defaultPostCount支持tag_slug/category_slug过滤getPost(slug)获取单篇文章调用butter.post.retrieve(slug)getMainMenu()获取主菜单从butter.content.retrieve([navigation_menu])中取名为Main menu的menu_itemsgetCategories()/getTags()分类/标签列表分别调用butter.category.list()/butter.tag.list()searchPosts({ query })关键词搜索调用butter.post.search(query)落地页的分页拉取是一个典型实现展示了如何处理 CMS API 的分页元数据export async function getLandingPages() { let paginatedLandingPages []; let currentPage 1; while (!!currentPage) { const landingPagesData await getLandingPagesData(currentPage); paginatedLandingPages.push(...landingPagesData.pages); currentPage landingPagesData.nextPage; } return paginatedLandingPages; }其中getLandingPagesData返回pages / prevPage / nextPage三元组nextPage来自响应meta.next_page为null时循环终止。所有函数统一采用try/catch抛出e.response.data.detail把 CMS 侧错误以可读形式上抛由页面层的catch决定降级策略返回notFound或空数组。四、静态生成在各页面的具体落地README 明确说明该示例展示的是 Next.js 的 Static Generation 能力。对照源码五种页面使用了三种数据获取策略1. 博客列表纯静态pages/blog.jspages/blog.js 使用getStaticProps拉取文章与分类并在 API 失败时降级为空列表而非报错export async function getStaticProps() { const butterToken process.env.NEXT_PUBLIC_BUTTER_CMS_API_KEY; if (butterToken) { try { const blogPosts (await getPostsData()).posts; const categories await getCategories(); return { props: { posts: camelcaseKeys(blogPosts), categories } }; } catch (e) { console.log(Could not get posts, e); return { props: { posts: [], categories: [] }, }; } } return { props: { posts: [], categories: [] } }; }注意两处工程细节camelcaseKeys把 Butter API 返回的 snake_case 字段如category_slug统一转成 camelCase使 React 侧属性访问更符合习惯if (butterToken)守卫与前述重定向策略呼应。2. 动态路径 fallback落地页与文章详情页pages/landing-page/[slug].js 的getStaticPaths在构建期列出所有落地页 slugexport async function getStaticPaths() { const butterToken process.env.NEXT_PUBLIC_BUTTER_CMS_API_KEY; if (butterToken) { try { const landingPages await getLandingPages(); return { paths: landingPages.map((page) /landing-page/${page.slug}), fallback: true, }; } catch (e) { console.error(Couldnt load content for Landing pages., e); } return { paths: [], fallback: false }; } }fallback: true的意义在于构建期未预渲染的 slug 不会被拒绝而是先展示router.isFallback时的Preloader /加载态再在服务端补渲染getStaticProps。对应的getStaticProps同时拉取页面数据与最新 2 篇文章getPostsData({ page: 1, pageSize: 2 })供落地页尾部嵌入博客区块取数失败时返回notFound: true页面侧配合router.isFallback与!page两个分支分别渲染加载器与ErrorPage statusCode{404}。pages/blog/[slug].js 遵循完全相同的模式并额外展示了 SEO 元数据的写法从文章字段生成title、meta description以及 Open Graph / Twitter Card 标签正文通过dangerouslySetInnerHTML注入 CMS 返回的 HTML配图则使用next/imagelayoutfillobjectFitcover。3. ISR 增量再验证分类页pages/blog/category/[slug].js 在getStaticProps中返回了revalidate: 1return { props: { posts: camelcaseKeys(blogPosts), categories, slug }, revalidate: 1, };这意味着分类页在首次请求生成后最多 1 秒就会触发后台再验证——CMS 中该分类的新文章几乎实时出现在已缓存的静态页面上。getStaticPaths则遍历getCategories()生成/blog/category/:slug路径集合同样使用fallback: true。4. 搜索页SSRpages/blog/search.jspages/blog/search.js 是唯一采用服务端逐请求渲染的页面因为搜索词无法在构建期枚举export async function getServerSideProps({ query: { query } }) { const blogPosts await searchPosts({ query }); const categories await getCategories(); return { props: { posts: camelcaseKeys(blogPosts), categories, query }, }; }这与 README 中already-implemented search functionality的描述对应搜索走 ButterCMS 的post.search接口每次请求实时执行。5. 全局菜单_app.js 的 getInitialProps主菜单不是页面级数据而是全局数据因此放在 pages/_app.js 的getInitialProps中获取并注入到HeaderSection/FooterSectionMyApp.getInitialProps async (appContext) { const appProps await App.getInitialProps(appContext); const authToken process.env.NEXT_PUBLIC_BUTTER_CMS_API_KEY; let mainMenu []; if (authToken) { try { mainMenu await getMainMenu(); } catch (e) { console.error(Couldnt load main menu links., e); } } return { ...appProps, mainMenu }; };同文件中还通过Router.events的routeChangeStart/Complete/Error事件驱动全局Preloader实现路由切换时的加载动画。五、next.config.js路由重写与远程图片域examples/cms-buttercms/next.config.js 除前述redirects外还包含两类配置首页重写——把根路径固定指向 ButterCMS 中的样例落地页async rewrites() { return [ { source: /, destination: /landing-page/landing-page-with-components, }, ]; },远程图片白名单——next/image默认禁止加载任意外域图片而 Butter 的媒体托管在cdn.buttercms.com因此需要显式声明images: { remotePatterns: [ { protocol: https, hostname: cdn.buttercms.com, port: , pathname: /my-account/**, }, ], },/my-account/**的 pathname 限定说明只放行当前账号媒体空间下的资源。六、落地页的分节组件模式落地页是 CMS 驱动的典型场景营销页的区块顺序与类型都由内容方在后台配置。pages/landing-page/[slug].js 中按 CMS 返回的page.fields.body数组逐节渲染{page.fields.body.map(({ type, fields: sectionData }, index) ( LandingPageSection key{index} type{type} sectionData{sectionData} / ))}components/landing-page-sections/landing-page-section.js 负责把type映射到具体组件且每个组件都用next/dynamic动态导入、失败时回退到MissingSectionconst sectionsComponentPaths () ({ hero: dynamic(() import(.../hero).catch(() () MissingSection), { loading: Preloader }), two_column_with_image: dynamic(() import(.../two-column-with-image).catch(() () MissingSection), { loading: Preloader }), features: dynamic(() import(.../features).catch(() () MissingSection), { loading: Preloader }), testimonials: dynamic(() import(.../testimonials).catch(() () MissingSection), { loading: Preloader }), }); const SectionComponent sectionsComponentPaths()[type] || MissingSection;从源码结构看这套类型 → 动态组件缺失兜底的映射表使 CMS 端新增/删减区块类型不会直接击穿前端未知type渲染占位组件而非报错未匹配到的区块数据走MissingSection。七、预览模式Preview Mode实战README 的 Step 4 描述了本示例最有实用价值的功能之一草稿内容预览。行为与开启方式如下在 ButterCMS 后台新建一篇博客标题设为Draft Post Test填入任意正文与摘要关键不要点击 Publish而是点击Save Draft先在.env.local中设置PREVIEWfalse并重启本地开发服务器访问博客列表如http://localhost:3000/#blog——此时看不到这篇草稿因为其状态尚未变为published随后从.env.local中删除PREVIEWfalse即回到默认开启状态刷新后新草稿文章即出现在列表中。结合 lib/api.js 第 5–11 行的代码可以确认其机制预览开关直接作为Butter(apiKey, preview)的第二个参数传给 SDK由 API 侧决定草稿可见性由于默认值为开启本地开发时草稿默认可见而生产部署若不希望暴露草稿应显式设置PREVIEWfalse。提示README 还建议在 ButterCMS 后台为部署在 Vercel 上的页面配置 Preview URL即可在 Butter 账号内对线上站点做实时内容预览该功能属于 ButterCMS 平台侧能力需在外部后台配置。八、部署到 VercelREADME 的 Step 5 给出两条部署路径从官方模板一键部署README 提供了 Vercel Deploy 按钮链接点击后会在你的 Git 账号中复制一份 starter 项目并立即部署同时引导你填入NEXT_PUBLIC_BUTTER_CMS_API_KEY环境变量形成完整的内容工作流。从仓库文件看一键部署所需的元数据就写在 app.json 中{ name: ButterCMS Next.js Starter Project, description: Drop-in proof-of-concept NextJs app, fully integrated with your ButterCMS account., repository: https://github.com/ButterCMS/nextjs-starter-buttercms, keywords: [Next.js, buttercms, cms, blog], buildpacks: [{ url: heroku/nodejs }], env: { NEXT_PUBLIC_BUTTER_CMS_API_KEY: { description: The API token of your ButterCMS account, value: } } }env段声明了部署时必须提供的NEXT_PUBLIC_BUTTER_CMS_API_KEY值为空需部署者填入这是部署清单与环境变量的直接对应关系。部署自己的本地项目对已做修改的本地项目将其推送到 GitHub / GitLab / Bitbucket 并导入 Vercel。重要导入时务必在 Vercel 控制台的Environment Variables中配置与本地.env.local一致的变量至少包括NEXT_PUBLIC_BUTTER_CMS_API_KEY以及按需的PREVIEW否则线上会触发上文所述的/missing-token重定向所有页面都落到提示页。小结该示例可借鉴的工程模式以 examples/cms-buttercms 为样本CMS 驱动型 Next.js 站点可提炼出以下可复用模式单一 API 封装层所有 CMS 调用集中在lib/api.js页面层只消费函数而非 SDK便于替换数据源静态生成为主、按需降级列表/详情用getStaticPaths(fallback: true)getStaticProps高频更新的分类页用revalidate: 1的 ISR不可枚举的搜索用getServerSideProps缺凭据友好环境变量守卫条件redirectsmissing-token提示页让项目在无 Key 状态下可运行、可诊断CMS 内容容错API 失败时页面降级为空数据或 404未知落地页区块类型回退到占位组件预览模式默认开启PREVIEW未设置即视为草稿可见降低本地调试成本。除本示例外同一目录下的其他 CMS 集成可作横向参考例如 cms-agilitycms、cms-contentful、cms-datocms、cms-ghost、cms-prismic、cms-sanity、cms-storyblok、cms-wordpress 以及 blog-starter。【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Next.js 结合 ButterCMS 构建静态生成内容站的完整实战：cms-buttercms 示例解析

相关推荐

Buzz｜离线音频转文字一次到位：本地 Whisper 转录，会议录音轻松整理

SEO与UX协同指南：从用户体验优化到关键词排名的完整实践

10分钟刷出第一个固件：QMK 自定义键盘上手教程

更多资讯

加密资产价值投资：策略、模型与风险管理

AI答非所问？一文读懂Token、参数与Transformer的底层逻辑

Markdown转Word全攻略：工具对比与高级技巧

量子加密货币：技术原理与投资价值解析

千笔平台：AI驱动的学术研究全流程革新

逆向拆解六款开源RAG：从架构共性到自研蓝图与避坑指南

今日更新

PLFM_RADAR：从被动告警到主动感知的微服务健康监控系统

SPI隔离设计实战：MAX14431BAEE+与STM32F407工业级应用

数字隔离器如何根治SPI通信地环路干扰：MAX14431与TM4C129实战

本周精选

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

本月热门

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

读完文章，想聊聊您的网站？