2023-08-15 13.21.03.gif

从构思到上线的全过程，开发中遇到一些未知问题，也都通过查阅资料和源码一一解决，小记一下望对正在使用或即将使用`Nextjs`开发的你们有所帮助。 ### 那些年我开发过的博客就挺有意思，域名，技术栈和平台的折腾史 * 2018年使用`hexo`搭建了个静态博客，部署在`github pages` * 2020年重新写了博客，`vue`，`nodejs`，`mongodb`三件套，使用`nginx`部署在云服务器上 * 2023年云服务器过期了，再一次重写了博客，`nextjs`为基础框架，部署在`vercel`上 ### 背景因为日常开发离不开终端，正好也有重写博客的想法，打算开发一个不只是看的博客网站，所以模仿终端风格开发了[Yucihent](https://yucihent.space/)。 ### 技术栈 `nextjs` [更多技术栈](https://yucihent.space/about) 选用`nextjs`是因为`next13`更新且稳定了`App Router`和一些其他新特性。 ### 设计简约为主，首页为类终端风格，`prompt`样式参考了`starship`，也参考过`ohmyzsh themes`，选用`starship`因为觉得更好看。 ### 交互通过手动输入或点击列出的命令进行交互，目前可交互的命令有： * `help` 查看更多 * `list`和`ls` 列出可用命令 * `clear` 清空所有输出 * `posts` 列出所有文章 * `about` 关于我后续会新增一些命令，增加交互的趣味。 ### 暗黑模式 > 基于`tailwind`的`dark mode`和`next-themes` 首先将`tailwind`的`dark mode`设置为`class`，目的是将暗黑模式的切换设置为手动，而不是跟随系统。 ```js // tailwind.config.js module.exports = { darkMode: 'class' } ``` 新建`ThemeProvider`组件，用到`next-themes`提供的`ThemeProvider`，需要在文件顶部使用`use client`，因为`createContext`只在客户端组件使用。 ```tsx '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 {children} } ``` 在`app/layout.tsx`中使用`ThemeProvider`，设置`attribute`为`class`，这是必要的。 ```tsx {children} ``` `next-themes`提供了`useTheme`，解构出`theme`和`setTheme`用于手动设置主题。综上基本实现暗黑模式切换，但你会在控制台看到此报错信息：`Warning: Extra attributes from the server: class,style`，虽然它并不影响功能，但终究是个报错。作为第三方包，可能存在水合不匹配的问题，经查阅资料，禁用`ThemeProvider`组件预渲染消除报错。资料： * [Warning: Extra attributes from the server: style](https://github.com/vercel/next.js/discussions/22388) * [Disabling SSR on specific components](https://nextjs.org/docs/messages/react-hydration-error#solution-2-disabling-ssr-on-specific-components) ```tsx const NoSSRThemeProvider = dynamic(() => import('@/components/ThemeProvider'), { ssr: false }) {children} ``` ### 类终端 > 由输入和输出组件组成，输入的结果添加到输出list中 #### 命令输入的打字效果 Alt Text

定义打字间隔100ms，对键入的命令for处理，定时器中根据遍历的索引延迟赋值。 ```ts 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`，键入命令后都自动滚动到页面底部，使用了`scrollIntoView`api，作用是让调用这个api的容器始终在页面可见，`block`参数设置为`end`表示垂直方向末端对其即最底端。 ```tsx const containerRef = useRef(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`配置 ```js // next.config.js import createMDX from '@next/mdx' const nextConfig = {} const withMDX = createMDX() export default withMDX(nextConfig) ``` 接着在应用根目录下新建`mdx-components.tsx` ```ts // 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`。 ```js // @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`使用该插件。 ```js // tailwind.config.js module.exports = { plugins: [require('@tailwindcss/typography')] } ``` 在外层标签上添加`prose`的className，`prose-invert`用于暗黑模式。 ```tsx

{mdx}

``` 综上我们实现了对mdx的样式支持，然而有一点是`@tailwindcss/typography`并不会对mdx代码块中代码进行高亮。 ### 代码高亮 > 写文章或多或少都有代码，高亮是必不可少，那么`react-syntax-highlighter`该上场了定义一个`CodeHighligher`组件 ```tsx // 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 ( {code} ) } ``` `react-syntax-highlighter`高亮代码可用`hljs`和`prism`，我在这使用的`prism`，两者都有众多代码高亮主题可供选择，lang如果没标注则默认设置为`javascript`也可以简写为`js`，值得注意的是如果是使用`hljs`，则必须写`javascript`，不可简写为`js`，否则代码高亮失败，这一点`prism`更加友好。同时可通过`useTheme`实现亮色，暗色模式下使用不同代码高亮主题。组件写好了，该如何使用？上面讲到过mdx的解析，在`useMDXComponents`重新渲染`pre`标签。 ```tsx // 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 } } } ``` mdx文件中代码块会被解析成`pre`标签，可以对`pre`标签返回值作进一步处理，即返回高亮组件，这样可实现对代码高亮，当然高亮主题很多，选自己喜欢的。 ### 文章 #### 元数据 > 文章一些信息如标题，描述，日期，作者等都作为文章的元数据，使用`yaml`语法定义 ```yaml --- title: '文章标题' description: '文章描述' date: '2020-01-01' --- ``` @next/mdx默认不会按照`yaml`语法解析，这会被解析成`h2`标签，然而我们并不希望元数据被解析成h2标签作为内容展示，更希望拿这类数据做其他处理，为了正确解析`yaml`，需要借助`remark-frontmatter`来实现。使用该插件，注意需要修改next配置文件名为`next.config.mjs`，因为`remark-frontmatter`只支持`ESM`规范。 ```js // next.config.mjs 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`读取文章目录内容，但是这仅仅是拿到文章名称的集合。 ```ts const POST_PATH = path.join(process.cwd(), 'mdxs/posts') // 文章名称集合 export function getPostList() { return fs.readdirSync(POST_PATH).map((name) => name.replace(/\.mdx/, '')) } ``` 文章列表中展示的是标题而不是名称，标题作为文章的元数据，通过`gray-matter`的`read`api读取文件可获取（也可以使用`fs.readFileSync`） read返回`data`和`content`的对象， `data`是元数据信息，`content`则是文章内容。 ```ts 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`文件 ```tsx export default function LoadMDX(props: Omit) { const { slug, title, date } = props const DynamicMDX = dynamic(() => import(`@/mdxs/posts/${slug}.mdx`), { loading: () =>

}) return ( <>

{title}

{date}

) } ``` ### [generateStaticParams](https://nextjs.org/docs/app/api-reference/functions/generate-static-params) > 优化文章列表跳转详情的速度在文章详情组件导出`generateStaticParams`方法，这个方法在构建时静态生成路由，而不是在请求时按需生成路由，一定程度上提高了访问详情页速度 ```ts 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`，导入对应仓库即可，也可使用vercel提供的模版新建一个，后续我们每次提交代码都会自动化部署。 Alt Text

有自己域名的可以在Domains中添加，然后去到你买域名的地方添加对应DNS解析即可。 ### 总结开发中遇到了一些坑： 1. `next-themes`报错`Warning: Extra attributes from the server: class,style`，通过issues和看文档，最终找到了方案 2. `mdx-components`组件的命名，经多次测试发现只能命名为`mdx-components`，阅读@next/mdx的源码也验证了 3. 语法高亮，开始使用的`hljs`，mdx中的代码块写的`js`，部署到线上后发现代码并没有高亮，然后改用了`prism`正常高亮，又是阅读了`react-syntax-highlighter`源码发现hljs的语言集合中并没有`js`，所以无法正确解析，只能写成`javascript`，而`prism`两者写法都支持 4. 首页的`posts`命令是运行在客户端组件中，fs无法使用，因此获取文章的方案使用fetch请求api 5. 使用`remark-frontmatter`解析yaml无法和`mdxRs: true`同时使用，否则解析失败。添加此配置项表示使用基于`rust`的解析器来解析`mdx`，可能是还未支持的缘故 ```js module.exports = withMDX({ experimental: { mdxRs: true } }) ``` 后续更新： 1. 会新增`Weekly`周刊模块，关注前端技术的更新 2. 文章详情页添加上一篇和下一篇，更方便的阅读文章