react-admin.cn 上线总结 - Readme

2023-blog

随着 http://www.react-admin.cn 的上线，今天总结一下这个项目的点点滴滴。这项目有几个模块组成，分别是

• Dumi： 提供静态文档的生成支持，满足Markdown格式转化为html并串联成一个网站的需求。

  仓库地址 https://gitee.com/jikey/react-admin-cn
  技术栈为：Dumi,

• Next：满足SEO前提下动态页面实现

  仓库地址 https://gitee.com/jikey/react-admin-cn
  技术栈为：Next, Antd, Ahooks, Bytemd, Tailwindcss

• Vue3: 后台管理

  仓库地址 https://gitee.com/jsfront/vue3-tiger-admin
  技术栈为：Vue3, Arce, VueUse, UnoCSS,

• Nestjs: 提供基础API数据源

  仓库地址 https://gitee.com/jsfront/nest-admin-api
  技术栈为：Nestjs, Mysql, Typeorm,

先从全局角度总结一下：

• 定位

  最原始的出发点是为react开发者提供一个以管理模板为核心，其它资源为辅助的信息知识类平台。能匹配管理模板及周边几个关键字相关的内容整合到一起，方便筛选查找。

• 目标用户

  与React相关的开发者

• 技术选型

  react 首选next，后端其实首推go，奈何此项目周边以前端为主的群体比较多，所以选择nest，备选koa2，数据库为mysql

• 代码组织

  采用的是Pnpm Monorepo, Monorepo 是把多个工程放到一个 git 仓库中进行管理，共享，复用代码等的工具。 开发时模块相互引用，发布时模块独立打包。这样代码能复用，发布又灵活，方便后续的扩展。比如后续要加个Admin平台，直接在apps中创建模块即可。

1. Dumi

1.1 基本介绍

Dumi 近期发布2.x版本，初步评估还是满足简单Markdown转换为文档平台的需求。
对Node版本有特殊要求，最低支持 Node.js v14 版本，因为在Pnpm中为了平衡Nest，最后运行版本为Node 16.0.0

1.2 如何发布上线

上线提前，基础配置约定好，减免后期踩坑的风险。比如Dumi要部署到二级目录http://react-admin.cn/doc，那除了配置base之外还要配置publicPath。

export default defineConfig({
  base: BaseUrl,
  publicPath: BaseUrl, // 打包文件时，引入地址生成 publicPath/xxx.js
});

打包

$ cd react-admin-cn\apps\md
$ pnpm build

然后上传 react-admin-cn\apps\md\dist目录中的文件到wwwroot/domain/doc目录即可。

2. Next介绍

Next要求Node最低版本为Node.js 14.6.0，

2.1 基本介绍

Nextjs 近期发了13，增加了快如闪电的Turbopack，在命令行手工开启，next dev --turbo，为了项目快速开发，此项目暂时没有开启。其它新特性：NextJS 13发布，包含大量新特性。

有几个插件用的还是比较方便的：

• next-progress
  页面顶部进度条，需要放到Suspense中。

• @carbon/icons-react
  Icons的扩展方案，使用起来也非常的方便

import { OverflowMenuHorizontal } from '@carbon/icons-react'
<OverflowMenuHorizontal />

• @nextui-org/react
  antd 的备份方案，4.x antd的翻页组件有bug，暂时用nextui来代替。

• lodash
  只用了debounce，也可以使用lodash-es版本，偶尔打包时会报错，所以选择稳定版本。

// 疯狂点击只响应最后一次
const onSearch = debounce(() => {
  onEmit()
}, 500)

• Tailwindcss
  本来我迷恋于Unocss的灵活和速度，可惜在Nextjs中热更新容易失去响应，只能换回Tailwindcss，虽然Unocss也提供了一个Nextjs下的案例。

• @bytemd/react
  bytemd是字节开发的一款富文本编辑器，可用于vue,react，主题可以使用juejin-markdown-themes，虽然名叫juejin，其它里边有很多风格的css选择，具体在这个 node_modules\juejin-markdown-themes\dist 目录下。

• qrcode.react
  其中一个页面需要分享展示用到二维码，用的这款，按照文档使用起来也没有大的问题。

• react-copy-to-clipboard
  按钮复制用这款，也没有什么大的问题。

• react-infinite-scroll-component
  滚动加载用到了这款，出现的问题是出现滚动条，添加样式强制显示即可隐藏滚动条。

<InfiniteScroll
    style={{ overflow: 'visible' }}
    hasMore={hasMore}
    loader={(
    <div className="text-center mt-5">
        <Spin indicator={antIcon} />
    </div>
    )}
>text</InfiniteScroll>

2.3 技术栈

2.3 开发工具

2.4 文件结构

├─.next // 开发目录
├─.out // 发布目录
├─api // 请求文件
├─components // 公共组件
├─config // 配置
├─context
├─hooks 
├─layouts // 布局文件
├─pages // 页面
├─public // 静态资源
├─styles // 所有 Scss 文件
└─utils // 工具文件

2.5 如何在本地运行

根目录下运行 pnpm install，然后运行 pnpm dev，最后执行的是：

pnpm --stream -r dev

也可以只启动子应用，进入子目录下运行pnpm dev。比如：

$ cd react-admin-cn\apps\md
$ pnpm dev
$ cd react-admin-cn\apps\ssr
$ pnpm dev

其它Node版本信息

// 切换环境
nvm install 16.0.0
nvm use 16.0.0
// 安装依赖
npm install
// 启动项目
npm start
// 清除 node_modules
npm run clean
// 全局安装 rimraf 之后方可使用
npm i rimraf -g
// 清除 node_modules 重新安装依赖
// 等同于 npm run clean && npm install
npm run reinstall

2.6 如何发布上线

需要注意的是：Nextjs的开发运行目录和打包上线目录默认都是.next，所以，打包输出结果要仔细看，要不然会把开发时的文件误上传。解决办法就是修改打包后输出目录：

// next.config.js
module.exports = {
  distDir: '.out',
}
// .gitignore
# next.js
/.next/
/out/
/.out/

2.6.1 Nginx配置

首先在nginx增加配置，转发nextjs的启动端口。
Nextjs虽然支持basePath进行二级目录的部署，可惜一刷新又出现basePath路径找不到的情况，只能在根目录部署。

location / {
  proxy_pass http://127.0.0.1:3600/;
  proxy_http_version 1.1;
  proxy_set_header Host $host;
}

2.6.2 启动Nextjs

根目录新建ecosystem.config.js，然后用pm2启动这个文件就可以了。

module.exports = {
  apps: [{
    name: 'react-admin-ssr',
    script: 'npm',
    args: 'start',
    cwd: '/www/wwwroot/react-admin.cn',
    autorestart: true,
    watch: true,
    // 不用监听的文件
    ignore_watch: [
      'node_modules',
      'logs'
    ],
    max_memory_restart: '1G',
    env: {
      NODE_ENV: 'development'
    },
    env_production: {
      NODE_ENV: 'production',
      BASE_PATH: "",
      PORT: 3006
    }
  }]
}

然后根据域名访问，如果出现500，说明后端相关有问题，查看Nginx, Pm2日志进行排错。

2.6.3 发布问题

• Favicon 图片不能拷贝到发布目录
  就算安装url-loader也不能解决，解决办法，转换为Base64图片。
• 图片路径
  文档讲可以用 /，然后打包后还是路径丢失

import Image from 'next/image'
import Logo from '@/public/images/logo.png'

• 手工调整buildid
  Nextjs前台静态资源会识别版本信息，最终影响生成目录路径在 /.next/static下，可以手工修改也可以是Git commit id。

generateBuildId: async () => 'v1',

• image
  images中添加允许域名

images: {
    domains: ['react-admin.cn'],
},

• package.json
  需要上传package.json到根目录然后在服务端全量安装node_modules
• Nginx 缓存
  在其它机型上没有碰到这个问题，只有在腾讯云上碰到这个问题，代理转发有缓存，需要清目录后杀掉进程后启动nginx

$ cd /www/server/nginx/proxy_cache_dir // nginx缓存目录
$ pkill nginx // 强制关闭
$ /etc/init.d/nginx start // 启动
$ /etc/init.d/nginx stop
$ /etc/init.d/nginx restart

• swcMinify 设置
  swcMinify 13之后就默认为true了，然后Bytemd打包发布就报错了，

TypeError: Cannot read properties of undefined (reading 'context')

然后设置为false就没事了。
swc全称是Speedy Web Compiler，基于Rust语言的JS编译器，主要对标Babel，准备代替Babel。

3. 开发介绍

3.1 基本介绍

• 基础的工程采用Pnpm Monorepo的方式来搭建，在满足基础开发的需求上能够灵活扩展模块，并保持代码解耦。这方面的其它介绍：

  • Laffery - 基于pnpm搭建monorepo项目
  • BestAns - pnpm + workspace + changesets 构建你的 monorepo 工程

• 由于整体是React的相关技术栈，计划帮助文档部分由dumi来实现，可以快速的将基础的Markdown快速转化为页面，入口地址由Nginx来安排。

3.2 约定式路由

约定式路由式的开发，即 pages目录下所有文件夹层级为路由访问路径。比如 pages/admin/index.tsx，那访问的路径就是https://react-admin.cn/admin。
pages中除了路由文件之外不建议放其它文件，要放其它扩展名文件还需要在next.config.js中增加配置。

module.exports = {
  pageExtensions: ['mdx', 'jsx', 'js', 'ts', 'tsx']
}

3.3 基础布局

基础的布局由Layouts负责，共有这几个：

• default
  负责基础页面的上中下式布局
• custom
  备选

3.4 获取数据

Nextjs 共有两种渲染模式，这两个模式下有两种获取数据的方式

• 静态模式（默认），即在构建时生成 html，并每次请求时复用
  
  • getStaticProps 静态模式下使用，在构建时会调用该函数获取数据并返回到 props，会在构建时渲染生成 html
  • getStaticProps 中的 context 参数包含了常用的请求的 params，preview，previewData，locale 等参数

• 服务器端渲染模式，即每次请求时在服务器端重新生成 html。

  • getServerSideProps 服务器端渲染模式下使用，会在每次请求时先获取数据，接着重新生成 html 后再将页面返回到客户端。
  • getServerSideProps 中的 context 参数包含了常用的请求的 req、res、params、query 等参数

• axios
  页面上在useEffect中异步获取数据，这块的代码在浏览器端运行。

3.5 SEO增强

通过 next/head 组件增加页面的meta 的 keywords, description 标签。

3.6 更新到Next.js 13

• Title变化

Next.js 12

<title>首页 - {title}</title>

Next.js 13

`<title>{`首页 - ${title}`}</title>`

• Link的变化

Next.js 12

<Link href=""><a target="_blank" rel="noreferrer">{title}</a></Link>

Next.js 13

<Link href="" target="_blank" rel="noreferrer">{title}</Link>

用这个命令全局替换，然后全局校验Eslint

$ npx @next/codemod new-link .

如果还想找回此文，您可以点右上角 💖Star 💖 收藏 + 支持

还可以加Q群进行反馈交流：

• Node交流群 422910907
• React交流群 530415177
• Javascript交流群 492107297