企业官网建设流程全解析

1. 从零搭一个 Next.js SSR 博客，为什么值得折腾

Next.js SSR 博客，说白了就是让服务器先把页面渲染成完整 HTML 再发给浏览器，爬虫拿到的是带内容的页面，而不是一个空壳。这件事对做技术博客的人特别重要：你写了几十篇文章，结果搜索引擎只收录了首页，那种感觉比代码跑不通还难受。Claude Code 在这里的角色，是帮你把「数据层 → SEO → 主题 → 页面」这条链路一次性铺好，而不是让你在十几个配置文件之间来回翻文档。

我这次要交付的东西很具体：一个基于 Next.js App Router 的 SSR 博客骨架，包含可复制的next.config、generateMetadata配置、暗黑模式 CSS 变量，以及 Lighthouse SEO 评分和主题切换的验证步骤。适合谁？适合已经会一点 React、想认真做内容站、但不想被 SEO 细节拖死的人。整条链路里，模型调用统一走 TaoToken 的 Key，省得你在多个平台之间切来切去。

先说清楚一个前提：SSR 不等于「一定 SEO 满分」。SEO 满分靠的是元数据完整、结构化数据正确、canonical 不重复、sitemap 能被抓。SSR 只是保证内容在首屏 HTML 里。这两件事要分开看，下面会一步步落地。

2. TaoToken 前置：统一 Key 与 Claude Code 接入

在动手写代码之前，先把模型调用这条线理顺。TaoToken 提供的是统一的 API 入口，你拿一个 Key 就能在 Claude Code 这类工具里调用模型，不用为每个模型单独配一套凭证。官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 基址是 https://taotoken.net/api 。

接入 Claude Code 的典型做法，是在环境变量里配置基址和 Key。你可以这样操作：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="你的_TaoToken_Key"

配好之后，Claude Code 发出的请求就会走 TaoToken 的统一入口。这里有个细节：不同版本的 Claude Code 读取的环境变量名可能略有差异，如果发现没生效，先确认你用的工具文档里写的是ANTHROPIC_BASE_URL还是别的名字。Key 的创建在控制台的 API Keys 页面，地址是 https://taotoken.net/console/api-keys ，建议给这个 Key 起个能认出用途的名字，比如nextjs-blog-dev，方便后面轮换。

注意：Key 不要写进前端代码或提交到 Git 仓库。放在.env.local里，并确保.gitignore包含它。

如果你更想先在网页里验证模型能不能正常对话，可以用模型对话入口 https://taotoken.net/models 快速试一句；如果是长期做编码和 Agent 任务，Coding Plan 页面 https://taotoken.net/coding-plan 会更合适，额度模型不一样。接入文档在 https://taotoken.net/doc ，遇到参数问题先查这里。

3. 可复制配置：next.config、metadata 与暗黑模式骨架

3.1 next.config 与项目初始化

先建项目。用 App Router，因为generateMetadata和sitemap.ts这些能力都在这一代里：

npx create-next-app@latest my-blog --typescript --tailwind --app --src-dir cd my-blog npm install next-themes gray-matter remark remark-html reading-time

next.config.mjs里，SSR 博客最该关注的是图片和重定向。一个够用的骨架：

/** @type {import('next').NextConfig} */ const nextConfig = { reactStrictMode: true, images: { formats: ['image/avif', 'image/webp'], remotePatterns: [ { protocol: 'https', hostname: '**' }, ], }, async redirects() { return [ { source: '/feed', destination: '/feed.xml', permanent: true }, ]; }, }; export default nextConfig;

images.formats让 Next 优先输出 AVIF/WebP，这对 Lighthouse 的 Performance 分有直接帮助。redirects是给 RSS 做个别名，老读者用/feed也能跳过去。

3.2 metadata 配置：SEO 的核心

App Router 里，页面级 SEO 靠generateMetadata。下面这段可以直接放进src/app/posts/[slug]/page.tsx：

import type { Metadata } from 'next'; import { getPost } from '@/lib/posts'; const SITE_URL = 'https://your-domain.com'; export async function generateMetadata( { params }: { params: { slug: string } } ): Promise<Metadata> { const post = await getPost(params.slug); if (!post) return { title: '文章未找到' }; const url = `${SITE_URL}/posts/${post.slug}`; return { title: post.title, description: post.excerpt, alternates: { canonical: `/posts/${post.slug}` }, openGraph: { type: 'article', url, title: post.title, description: post.excerpt, publishedTime: post.date, modifiedTime: post.updated || post.date, tags: post.tags, }, twitter: { card: 'summary_large_image', title: post.title, description: post.excerpt, }, robots: { index: true, follow: true }, }; }

这里几个点值得单独说。alternates.canonical是防重复收录的关键，尤其是你同时有分页和标签页的时候。openGraph.type设成article而不是默认的website，社交平台抓取时才会按文章处理。robots显式写index: true比不写更稳，某些爬虫对缺省值的处理不一致。

结构化数据用 JSON-LD 注入，放在页面组件里：

const jsonLd = { '@context': 'https://schema.org', '@type': 'Article', headline: post.title, datePublished: post.date, dateModified: post.updated || post.date, author: { '@type': 'Person', name: post.author || '博主' }, mainEntityOfPage: { '@type': 'WebPage', '@id': url }, };

然后在 JSX 里用<script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }} />输出。Lighthouse 的 SEO 审计会检查这个。

3.3 暗黑模式 CSS 变量骨架

暗黑模式最容易踩的坑是「闪白」：页面先渲染亮色，JS 加载后再切暗色，用户眼前一白。解法是用next-themes配合 CSS 变量，让主题在 HTML 上就定好。

src/app/globals.css里定义变量：

:root { --color-bg: #ffffff; --color-text: #1a1a2e; --color-border: #e5e7eb; --color-accent: #3b82f6; } .dark { --color-bg: #0f172a; --color-text: #e2e8f0; --color-border: #334155; --color-accent: #60a5fa; } body { background-color: var(--color-bg); color: var(--color-text); transition: background-color 0.3s ease, color 0.3s ease; }

主题提供者包在根布局里：

'use client'; import { ThemeProvider } from 'next-themes'; export default function Providers({ children }: { children: React.ReactNode }) { return ( <ThemeProvider attribute="class" defaultTheme="system" enableSystem disableTransitionOnChange> {children} </ThemeProvider> ); }

attribute="class"让 next-themes 往<html>上加dark类，正好对上上面的.dark选择器。disableTransitionOnChange是防止切换瞬间所有元素一起过渡导致的卡顿感。

4. 验证请求：Lighthouse SEO 评分与主题切换

4.1 跑起来看首屏 HTML

先构建再启动，别用 dev 模式测 SEO，dev 模式的输出和产物不一样：

npm run build npm run start

打开一个文章页，右键「查看网页源代码」。你要能在源码里直接看到文章标题、正文段落、<link rel="canonical">和 JSON-LD 脚本。如果正文是空的，说明渲染没走 SSR，检查页面组件里有没有误加'use client'——加了就变客户端渲染了。

4.2 Lighthouse SEO 审计

用 Chrome DevTools 的 Lighthouse 面板，或者命令行：

npx lighthouse http://localhost:3000/posts/your-slug --only-categories=seo --view

SEO 满分通常卡在这几项：document没有<title>、缺 meta description、链接不可抓取、robots.txt无效。前面 metadata 配好了，这几项基本能过。如果 SEO 分没到 100，先看审计报告里具体哪条标红，别盲目改。

4.3 主题切换验证

验证暗黑模式有没有闪白，最直接的办法是把系统主题切成暗色，然后硬刷新页面（Ctrl+Shift+R）。如果页面在加载瞬间是白的再变暗，说明主题注入时机不对。正常情况下，<html>标签在首屏就带上了dark类。

再验证切换按钮：点一下应该在三态之间循环（亮 → 暗 → 跟随系统）。切换时观察有没有布局跳动，如果按钮位置变了，多半是图标尺寸不一致导致的，给按钮固定宽高即可。

5. 本篇常见错排查

报错一：generateMetadata不生效，标题还是默认的。检查这个函数是不是写在page.tsx里，而不是layout.tsx。layout 的 metadata 会被页面级覆盖，但页面级必须自己导出。另外确认函数是async的，返回的是Metadata对象。

报错二：暗黑模式切换后刷新又变回亮色。这是defaultTheme设成了light而不是system，或者enableSystem没开。next-themes 把用户选择存在 localStorage，如果没开 system 检测，刷新时读不到偏好就会回默认值。

报错三：Lighthouse 提示「图片没有明确的宽高」。Next 的<Image>组件需要你给width和height，或者用fill配合父容器定位。封面图建议用固定比例容器包一层，避免布局偏移（CLS）拉低 Performance 分。

报错四：sitemap 里出现了草稿文章。在getAllPostMetas里过滤draft字段，别只在列表页过滤。sitemap 生成函数如果直接读全部文件，草稿也会被写进去，搜索引擎抓到 404 或空页面对站点权重有影响。

报错五：canonical 指向了 localhost。把SITE_URL抽成环境变量，构建时注入。写死在代码里，本地测试没问题，一部署就全错。

6. 把这条链路用顺，后面就轻松了

这套骨架跑通之后，你新增一篇文章只需要往content/posts丢一个 Markdown 文件，metadata、sitemap、RSS 都会自动带上。真正花时间的不是写代码，而是把 SEO 的每个细节确认到位——canonical、结构化数据、robots、sitemap，一个都不能少。

如果你在接入模型调用时遇到 Key 或基址的问题，先去 API Keys 页面 https://taotoken.net/console/api-keys 确认 Key 状态，再对照接入文档 https://taotoken.net/doc 检查环境变量名。想先验证模型响应是否正常，用模型对话 https://taotoken.net/models 发一句话最快。长期做编码和 Agent 任务的话，Coding Plan https://taotoken.net/coding-plan 的额度模型更适合持续调用。

最后留一个我踩过的坑：别在layout.tsx里写死metadata的 title，页面级generateMetadata会覆盖它，但如果你忘了在页面里导出，用户看到的就是 layout 的默认标题。这个错误在本地开发时不容易发现，部署后看搜索结果才反应过来。