当前位置：首页 > news >正文

Nextjs(App Router) 开发记录

news 2025/8/4 3:49:18

在这里插入图片描述

最近业余在开发一款智能助理产品，记录开发过程中的一些问题以备忘，也是帮其他人防坑。

主要技术栈

本项目采用了前沿的技术栈来构建一个高性能且可维护的应用。选择了 Nx 作为构建管理和单一代码库解决方案，通过模块化和插件系统来扩展和优化开发流程、支持续集成。Next.js（App Router模式）为我们提供了服务器渲染和客户端渲染的能力，同时简化了路由配置。项目主要使用 Typescript 编写，这有助于捕捉类型错误并在编译时解决它们。

界面方面，Material UI和Tailwind CSS分别作为UI组件库和原子化CSS样式方案被引入，确保了快速且一致的UI开发体验。为了实现3D图形功能，我们集成了react-three-fiber，它是Three.js的一个 React 绑定。使用 Recoil 进行状态管理，它提供了一个直观的状态管理模型。

接口层，使用Apollo Client 来发送 GraphQL 请求和缓存，并将GraphQL转换为Cypher查询，以便与图数据库Neo4j交互。为了提高开发效率，我们还利用了 GraphQL Code Generator 来自动生成代码。关系数据库读写，采用 Prisma ORM，它可以跨多种数据库环境工作，并提供了强大的类型安全特性。

采用 Next Auth 实现用户认证。为了保证代码质量，我们引入了jest进行单元测试，eslint、commitlint和prettier用于代码风格和提交规范的检查，结合 VSCode 插件实现自动格式化、提交检查。此外，项目还探索了 WebAssembly 和 WebWorker 技术以增强应用性能

Nx - 基于插件的单一代码库构建管理系统
Next.js - 开发框架，采用 App Router 模式
Prisma ORM: 支持多数据库的 Node.js and TypeScript ORM
Material UI - UI组件库
Tailwindcss - 原子化 CSS 样式方案
Typescript - 基于 Javascript 的编程语言
react-three-fiber - Three.js 组件
Apollo Client - GraphQL 客户端
@neo4j/graphql - 将 GraphQL 转换为 Cypher, 作为图数据库 Neo4j 查询执行层
Recoil - 状态管理
Next Auth - Web 认证
GraphQL Code Generator- 基于 GraphQL Schema 生成代码的工具
其他: jest eslint commitlint prettier WebAssembly WebWorker docker…

Bug 坑

1. Nx 19.6.2 使用 pnpm 初始化失败

执行命令：npx create-nx-workspace --pm pnpm 可生成代码，但无法正常运行。查看错误日志：A project already exists in this directory

通过与npm创建的项目对比，发现缺少 @nx/react

解决：pn add -D @nx/react，之后 nx dev app 可运行

2. pnpm 用 dlx

pn run generate 报错：The "path" argument must be of type string. Received undefined

分析：实际执行的是 npx prisma generate --schema=./file-path ，可能是 npx 执行时缺少相关包或版本不一致导致。
解决：改用 dlx， pnpm dlx prisma generate

3. eslint 保存无法自动格式化

报错： Error: Cannot read config file TypeError: prettier.resolveConfig is not a function，可能原因：升级依赖后 eslint server 未重启,或版本不一致。
解决：

确认版本 eslint@^8.57.0 prettier@^3.3.3 ，重装依赖
重启 VS Code 的 ESLint Server ，快捷键 Ctrl + Shift + P 输入 ESLint 选择 ESLint: Restart ESLint Server

查看 ESLint 输出：
在这里插入图片描述

4. react-pdf 报错 TypeError: Promise.withResolvers is not a function

基于官方示例： https://github.com/wojtekmaj/react-pdf/tree/main/sample/next-app
解决：

创建utils/polyfilsResolver.ts

export type PromiseWithResolvers<T> = {promise: Promise<T>resolve: (value: T | PromiseLike<T>) => voidreject: (reason?: any) => void
}export function polyfillPromiseWithResolvers() {// @ts-ignoreif (!Promise.withResolvers) {// @ts-ignorePromise.withResolvers = function <T>(): PromiseWithResolvers<T> {let resolve: (value: T | PromiseLike<T>) => voidlet reject: (reason?: any) => voidconst promise = new Promise<T>((res, rej) => {resolve = resreject = rej})return { promise, resolve: resolve!, reject: reject! }}}
}

路由页面中添加：

import { polyfillPromiseWithResolvers } from '@xueji/utils'
import 'core-js/full/promise/with-resolvers.js'
polyfillPromiseWithResolvers()import Sample from './Sample'

具体客户端渲染组件： Sample.tsx

pdfjs.GlobalWorkerOptions.workerSrc = new URL('pdfjs-dist/build/pdf.worker.min.mjs', import.meta.url).toString()

参考：https://github.com/wojtekmaj/react-pdf/issues/1811

技巧

1. 自定义 VSCode 折叠显示

在这里插入图片描述
在.vscode/settings.json中添加：

  "explorer.fileNesting.enabled": true,"explorer.fileNesting.patterns": {"*.env": "$(capture).env.*","package.json": ".gitignore,.prettierrc,.prettierignore,.eslintrc.json,.eslintignore,.editorconfig......."}