博客开发小记: 构思到上线

2023.07.09约 6 分钟

技术

记录使用nextjs开发此博客的历程，遇到的问题以及解决方案。

那些年我开发过的博客

就挺有意思，域名，技术栈和平台的折腾史

2018 年使用hexo搭建了个静态博客，部署在github pages
2020 年重新写了博客，vue，nodejs，mongodb三件套，使用nginx部署在云服务器上
2023 年云服务器过期了，再一次重写了博客，nextjs为基础框架，部署在vercel上

背景

因为日常开发离不开终端，正好也有重写博客的想法，打算开发一个不只是看的博客网站，所以模仿终端开发了Yucihent。

技术栈

nextjs

选用nextjs是因为next13更新且稳定了App Router和一些其他新特性。

设计

简约为主，首页为类终端风格，prompt样式参考了starship，也参考过ohmyzsh themes，选用starship因为觉得更好看。

通过手动输入或点击列出的命令进行交互，目前可交互的命令有：

help 查看更多
list和ls 列出可用命令
clear 清空所有输出
posts 列出所有文章
about 关于我

后续会新增一些命令，增加交互的趣味。

暗黑模式

基于tailwind的dark mode和next-themes

首先将tailwind的dark mode设置为class，目的是将暗黑模式的切换设置为手动，而不是跟随系统。

// tailwind.config.js

module.exports = {
  darkMode: 'class'
}

新建ThemeProvider组件，用到next-themes提供的ThemeProvider，需要在文件顶部使用use client，因为createContext只在客户端组件使用。

'use client'

import { ThemeProvider as NextThemeProvider } from 'next-themes'
import type { ThemeProviderProps } from 'next-themes/dist/types'

export default function ThemeProvider({
  children,
  ...props
}: ThemeProviderProps) {
  return <NextThemeProvider {...props}>{children}</NextThemeProvider>
}

在app/layout.tsx中使用ThemeProvider，设置attribute为class，这是必要的

<ThemeProvider attribute="class">{children}</ThemeProvider>

next-themes提供了useTheme，解构出theme和setTheme用于手动设置主题

综上基本实现暗黑模式切换，但你会在控制台看到此报错信息：Warning: Extra attributes from the server: class,style，虽然它并不影响功能，但终究是个报错。作为第三方包，可能存在水合不匹配的问题，经查阅资料，禁用ThemeProvider组件预渲染消除报错。

资料：

const NoSSRThemeProvider =
  dynamic(() => import('@/components/ThemeProvider'), {
    ssr: false
  })

<NoSSRThemeProvider attribute="class">{children}</NoSSRThemeProvider>

类终端

由输入和输出组件组成，输入的结果添加到输出 list 中

命令输入的打字效果

定义打字间隔 100ms，对键入的命令 for 处理，定时器中根据遍历的索引延迟赋值。

const autoTyping = (cmd: string) => {
  const interval = 100 // ms
  for (let i = 0; i < cmd.length; i++) {
    setTimeout(() => {
      setCmd((prev) => prev + cmd.charAt(i))
    }, interval * (i + 1))
  }
}

滚动到底部

定义外层容器ref为containerRef，键入命令后都自动滚动到页面底部，使用了scrollIntoViewapi，让调用这个 api 的容器始终在页面可见， block参数设置为end表示垂直方向末端对其即最底端。

const containerRef = useRef<HTMLDivElement>(null)
useEffect(() => {
  containerRef.current?.scrollIntoView({
    behavior: 'smooth',
    block: 'end'
  })
}, [typedCmds])

MDX

何为mdx？即给md添加了jsx支持，功能更强大的 md，在 nextjs 中通过@next/mdx解析.mdx文件，它会将md和react components转成 html

安装相关包，后两者作为@next/mdx的peerDependencies

@next/mdx
@mdx-js/loader
@mdx-js/react

在next.config.js新增createMDX配置

// next.config.js

import createMDX from '@next/mdx'

const nextConfig = {}

const withMDX = createMDX()
export default withMDX(nextConfig)

接着在应用根目录下新建mdx-components.tsx

// mdx-components.tsx

import type { MDXComponents } from 'mdx/types'

export function useMDXComponents(components: MDXComponents): MDXComponents {
  return {
    ...components
  }
}

在app目录下使用.mdx文件，useMDXComponents组件是必要的，

需要注意的是此文件命名上有一定规范只能命名为mdx-components，不能为其他名称，也不可为MdxComponents，从@next/mdx源码中可以看出会去应用根目录查找mdx-components。

// @next/mdx部分源码

config.resolve.alias['next-mdx-import-source-file'] = [
  'private-next-root-dir/src/mdx-components',
  'private-next-root-dir/mdx-components',
  '@mdx-js/react'
]

至此就可以在 app 中使用mdx。

排版

为 mdx 解析成的 html 添加样式

解析 mdx 为 html，但并没有样式，所以我们借助@tailwindcss/typography来为其添加样式，在tailwind.config.js使用该插件。

// tailwind.config.js

module.exports = {
  plugins: [require('@tailwindcss/typography')]
}

在外层标签上添加prose的 className，prose-invert用于暗黑模式。

<article className="prose dark:prose-invert">{mdx}</article>

综上我们实现了对 mdx 的样式支持，然而有一点是@tailwindcss/typography并不会对 mdx 代码块中代码进行高亮。

代码高亮

写文章或多或少都有代码，高亮是必不可少，那么react-syntax-highlighter该上场了

定义一个CodeHighligher组件

// CodeHighligher.tsx

import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter'
import {
  oneDark,
  oneLight
} from 'react-syntax-highlighter/dist/cjs/styles/prism'
import { useTheme } from 'next-themes'

export default function CodeHighligher({
  lang,
  code
}: {
  lang: string
  code: string
}) {
  const { theme } = useTheme()
  return (
    <SyntaxHighlighter
      language={lang?.replace(/\language-/, '') || 'javascript'}
      style={theme === 'light' ? oneLight : oneDark}
      customStyle={{
        padding: 20,
        fontSize: 15,
        fontFamily: 'var(--font-family)'
      }}
    >
      {code}
    </SyntaxHighlighter>
  )
}

react-syntax-highlighter高亮代码可用hljs和prism，我在这使用的prism，两者都有众多代码高亮主题可供选择， lang 如果没标注则默认为javascript也可以简写为js，值得注意的是如果是使用hljs，则必须写javascript，不可简写为js，否则代码高亮失败，这一点prism更加友好。

同时通过useTheme实现亮色，暗色模式下使用不同代码高亮主题。

组件写好了，该如何使用？上面讲到过 mdx 的解析，在useMDXComponents重新渲染pre标签。

// mdx-components.tsx

import type { MDXComponents } from 'mdx/types'
import CodeHighligher from '@/components/CodeHighligher'

export function useMDXComponents(components: MDXComponents): MDXComponents {
  return {
    pre: ({ children }) => {
      const { className, children: code } = props
      return <CodeHighligher lang={className} code={code} />
    }
  }
}

mdx 文件中代码块会被解析成pre标签，可以对pre标签返回值作进一步处理，即返回高亮组件，这样可实现对代码高亮，当然高亮主题很多，选自己喜欢的。

文章元数据

文章一些信息如标题，描述，日期，作者等都作为文章的元数据，使用yaml语法定义

---
title: '文章标题'
description: '文章描述'
date: '2020-01-01'
---

@next/mdx 默认不会按照yaml语法解析，这会被解析成h2标签，然而我们并不希望元数据被解析成 h2 标签作为内容展示，更希望拿这类数据做其他处理，为了正确解析yaml，需要借助remark-frontmatter来实现。

使用该插件，注意需要修改 next 配置文件名为next.config.mjs，因为remark-frontmatter只支持ESM规范。

import createMDX from '@next/mdx'
import frontmatter from 'remark-frontmatter'

const nextConfig = {}

const withMDX = createMDX({
  options: {
    remarkPlugins: [frontmatter]
  }
})
export default withMDX(nextConfig)

yaml 被正确解析了那么我们可以使用gray-matter来获取文章元数据

文章列表

由于 app 目录是运行在nodejs runtime下，基本思路是用 nodejs 的fs模块去读取文章目录即mdxs/posts，读取该目录下的所有文章放在一个 list 中。

使用fs.readdirSync读取文章目录内容，但是这仅仅是拿到文章名称的集合。

const POST_PATH = path.join(process.cwd(), 'mdxs/posts')

// 文章名称集合
export function getPostList() {
  return fs.readdirSync(POST_PATH).map((name) => name.replace(/\.mdx/, ''))
}

文章列表中展示的是标题而不是名称，标题作为文章的元数据，通过gray-matter的readapi 读取文件可获取（也可以使用fs.readFileSync） read 返回data和content的对象， data是元数据信息，content则是文章内容。

export function getPostMetaList() {
  const posts = getPostList()

  return posts.map((post) => {
    const {
      data: { title, description, date }
    } = matter.read(path.join(POST_PATH, `${post}.mdx`))

    // 使用fs.readFileSync
    // const post = fs.readFileSync(path.join(POST_PATH, `${post}.mdx`), 'utf-8')
    // const {
    //   data: { title, description, date }
    // } = matter(post)

    return {
      slug: post,
      title,
      description,
      date
    }
  })
}

上述方法中我们拿到了所有文章标题，描述信息，日期的 list，根据 list 渲染文章列表。

文章详情

文章列表中使用Link跳转到详情，通过dynamic动态加载文章对应的mdx文件

export default function LoadMDX(props: Omit<PostMetaType, 'description'>) {
  const { slug, title, date } = props

  const DynamicMDX = dynamic(() => import(`@/mdxs/posts/${slug}.mdx`), {
    loading: () => <p>loading...</p>
  })

  return (
    <>
      <div className="mb-12">
        <h1 className="mb-5 font-[600]">{title}</h1>
        <time className="my-0">{date}</time>
      </div>
      <DynamicMDX />
    </>
  )
}

generateStaticParams

优化列表跳转详情的速度

在文章详情组件导出generateStaticParams方法，这个方法在构建时静态生成路由，而不是在请求时按需生成路由，一定程度上提高了访问详情页速度

export async function generateStaticParams() {
  const posts = await fetch('https://.../posts').then((res) => res.json())

  return posts.map((post) => ({
    slug: post.slug
  }))
}

部署

项目是部署在 vercel，使用 github 登录后我们新建一个项目，点进去后会看到Import Git Repository，导入对应仓库即可，后续我们每次提交代码都会自动化部署。

有自己域名的可以在 Domains 中添加，然后去到你买域名的地方添加对应 DNS 解析即可。

总结

开发中遇到了一些坑：

next-themes报错Warning: Extra attributes from the server: class,style，通过 issues 和看文档，最终找到了方案
mdx-components组件的命名，经多次测试发现只能命名为mdx-components，阅读@next/mdx 的源码也验证了
语法高亮，开始使用的hljs，mdx 中的代码块写的js，部署到线上后发现代码并没有高亮，然后改用了prism正常高亮，又是阅读了react-syntax-highlighter源码发现 hljs 的语言集合中并没有js，所以无法正确解析，只能写成javascript，而prism两者写法都支持
首页的posts命令是运行在客户端组件中，fs 无法使用，因此获取文章的方案使用 fetch 请求 api
使用remark-frontmatter解析 yaml 无法和mdxRs: true同时使用，否则解析失败。添加此配置项表示使用基于rust的解析器来解析mdx，可能是还未支持的缘故

module.exports = withMDX({
  experimental: {
    mdxRs: true
  }
})