基于NUXT.JS搭建一款VUE版SSR前端框架（解决SPA应用的SEO优化优化问题）

2023-03-04 17:15 由北堂墨染发表于 #前端开发

小仙男·言在前

关于框架：为了解决VUE的SPA单页应用对SEO搜索引擎优化不友好的问题，这几天一直在调研各种SSR框架。比如doc.ssr-fc.com/ 和 fmfe.github.io/genesis-do 都是比较不错，且有自己理念和想法的框架。但是对于公司来说技术规范差异太大，团队学习成本比较高，思来想去，还是基于NUXT.JS自己搭建一套SSR框架慢慢完善吧。
关于本文档：本文档是从官网文档中摘录的一些重点内容，以及加入了自己的一些调整和对官网内容的理解和解释。
关于官网：NUXT中文网特别适合新手学习，文档及案例十分清楚详尽，可以说有手就行。但是，中文网的更新不及时，有些章节（比如fetch钩子中不能使用this）甚至存在明显错误，所以有一定技术水平的宝子，建议直接查看 NUXT英文官网。

【一、框架概述】

1、框架介绍

SSR 技术(即服务端渲染技术)，区别于原先纯Vue框架的SPA应用(即单页应用)。SPA应用只有一个index.html的入口文件，页面显示的所有内容均靠客户端JS进行渲染，对于搜索引擎（SEO）优化来说，整个网站只有一个空页面，十分不友好。而服务端渲染技术，是借助node.js作为框架服务端，在初次访问一个页面的时候，先在服务端预请求接口，并在服务端组装完成的html页面后，返回给客户端呈现。
Nuxt.js是基于Vue框架的一款服务端渲染框架，提供了特有的框架结构和服务端渲染声明周期。

2、开发环境

本框架基于Node.js+Webpack+vue+Nuxt.js进行开发，提供ElementUI作为UI框架。开发前需全局安装Node.js与webpack开发环境。
框架推荐Node.js版本为v16.15.0，最低版本不得低于12，推荐安装nvm或n等node版本管理工具。

3、分支要求

遵循[前端团队git仓库及版本管理规范]，即master分支只用于拉取框架代码，xxx_dev为开发分支，xxx_test为开发分支，xxx为生产分支。

3、关于本文档

本文档所述内容，已经是从官网中摘录的【重中之重】，开发前请【详尽】【仔细】【通读】本文档！！！尤其是【五、数据请求】与【六-8、重要Q&A】！！！
文档描述存在错误的地方，请以【NUXT英文官网】为准。

【二、启动与部署】

# 安装框架以来
$ npm install

# 启动本地开发环境，默认端口号：3000
$ npm run dev

# 编译并在生产环境启动
$ npm run build
$ npm run start

# 将网站打包成静态化页面
$ npm run generate

【三、框架结构】

详细目录结构介绍及使用，参照【六、其他规范与Q&A】

-- 框架根目录
  -- .nuxt        Nuxt运营和编译自动生成
  -- dist         执行Nuxt静态化时生成
  -- api          全局通用的Api请求函数（非Nuxt提供）
  -- assets       静态资源目录，存放全局css、image等
  -- components   自定义组件目录，此目录下组件无需引入，按需使用即可
  -- layout       布局文件，参考https://www.nuxtjs.cn/guide/views
  -- middleware   中间件，类似于路由守卫
  -- modules      模块，用于设置全局监听等，参考https://www.nuxtjs.cn/guide/modules
  -- pages        页面目录，Nuxt会根据此目录自动生成路由，参考https://www.nuxtjs.cn/guide/routing
  -- plugins      插件目录，自定义各种插件，参考https://www.nuxtjs.cn/guide/plugins
   > global.js    (全局变量与全局方法)
   > plugin.js    (全局引入第三方组件)
   > request.js   (全局请求封装)
   > filter.js    (全局过滤器封装)
   > util.js      (全局工具函数封装)
   > all.client.js(仅在客户端执行插件，暂时替代原app.vue)
     
  -- static       不需要webpack编译的静态文件，一般存放ico等文件
  -- store        Vue状态树，与原写法有所不同，参考https://www.nuxtjs.cn/guide/vuex-store
  -- utils        工具类包 （非Nuxt提供）
  .editorconfig   
  .gitignore
  env.js          环境变量配置，分dev、test、pro三种环境
  nux.config.js   Nuxt的所有配置项，参考https://www.nuxtjs.cn/api/configuration-build
  package-lock.json
  package.json
  README.md       框架使用文档
  ReleaseNote.md  版本更新说明

【四、生命周期】

-- Nuxt完整声明周期
  【服务端渲染】
    -- 全局
  nuxtServerInit    第一个：nuxt中第一个运行的生命周期
  RouteMiddleware   第二个：中间件，类似于原框架的路由导航守卫
    -- 组件
  validate          是用来校验url参数符不符合
  asyncData         Nuxt专属声明周期，可用于数据请求，只有page可用，子组件内部不可用
  beforeCreate      Vue声明周期，但是服务端会执行（不可用于数据请求，数据请求相关操作会在客户端执行）
  created           Vue声明周期，但是服务端会执行（同上）
  fetch             Nuxt专属声明周期，可用于数据请求， page和子组件都可用 
  
  【客户端渲染】
    -- 全局
  * `@/plugins/all.client.js` (并非Nuxt声明周期，是只在客户端运行的插件。此框架中用于暂时替代原框架中在App.vue中进行的全局初始化操作。)
    -- 组件
  beforeCreate
  created
  beforeMount
  mounted
  ... (其他Vue后续声明周期)

几点说明：

beforeCreate/created 是Vue的生命周期，但是会在服务端和客户端各执行一次，但这两个钩子，仅供了解，不能用于数据请求。
asyncData和fetch都是Nuxt提供的声明周期，都可用于数据请求。只是写法略有不同（参考后续章节【五、数据请求】）。
@/plugins/all.client.js 并非Nuxt声明周期，是只在客户端运行的插件。但是Nuxt框架去掉了app.vue，此插件的声明周期，近似于原来的app.vue，故暂时用于替代原框架中在App.vue中进行的全局初始化操作（是否恰当暂时不知）。

【五、数据请求】

1. 数据请求钩子

1.1 钩子相关说明

asyncData和fetch都是Nuxt提供的声明周期，都可用于数据请求，都会在服务端预请求数据进行组装；
asyncData只能在pages级别的页面中调用，在子组件内部不能调用；fetch则可以同时在页面和子组件中调用；
官方建议数据请求均采用asyncData，但为了保持与老框架写法的一致，本框架暂时建议采用fetch（后果未知）
fetch请求相比于asyncData的已知缺陷有：
- ① 数据请求较慢，本框架Demo，从index页进入Detail页，当使用fetch请求时，可明显看到浏览器选项卡的title出现一瞬间undefined
尽管beforeCreate/created也可以在服务端渲染，但是这两个钩子的数据请求操作只会在客户端执行，非特殊情况，切勿用于页面初始化。

1.2 asyncData

asyncData 中不能访问this，但是可以在第一参数中，拿到context上下文，使用context.app访问Vue根示例；
- context上下文还包含store、route、params、query等数据，详见context上下文
asyncData中无法拿到组件实例，不能访问组件实例中的data method等方法。
详细介绍：asyncData
【请求示例】

// ① 使用return返回的对象，将直接初始化到组件`data`中
async asyncData({app, params}) {
    const { code, data } = await app.$get('/policy/findById/'+params.id)
    return {detail: data}
},
// ② return一个Promise，将在Promise执行完成后，将数据初始化到组件`data`中
asyncData({app, params}) {
    return app.$get('/policy/findById/'+params.id).then(res => {
      return {detail: data}
    })
},
// ③ 第二个参数为callback回调函数，可直接传入数据，初始化到组件`data`中
asyncData({app, params}, callback) {
    app.$get('/policy/findById/'+params.id).then(res => {
      callback(null, {detail: data}) 
    })
},

1.3 fetch

fetch 分两种情况（新版本后支持第二种情况）：
- ① 第一个参数接受context上下文，则与asyncData一样，不能访问this和组件实例；（这种情况，也不支持像asyncData一样通过return或者回调函数修改data内容）
- ② 不接受任何参数时，则可以正常访问this。（可以近似的看成created的用法，区别是必须要使用await 或者return一个primary）
详细介绍：fetch英文文档（中文文档严重延迟，存在错误）
【请求示例】

// ① 使用return返回一个Promise
fetch() {
    return this.getDetail()
},
// ②  使用await/async
async fetch() {
    await this.getDetail()
},
methods: {
    // ① 使用await编写methods方法
    async getDetail(id){
        const { code, data } = await this.$get('/policy/findById/'+this.$route.params.id)
        this.detail = data
    }
    // ② 使用return Promise编写methods方法
    getDetail(id){
        return this.$get('/policy/findById/'+this.$route.params.id).then(resw => {
          this.detail = res.data
        })
    }
}

2. 数据请求方式

2.1 【框架推荐】使用vue实例直接调用

本框架会将$request/$get/$post挂在到vue根示例，建议直接只用this或上下文context.app调用
【请求示例】

// 以this调用为例，如果是在`asyncData`中，需要使用上下文`context.app`调用
// ① get
this.$get('/policy/findById/'+this.$route.params.id)
// ②  post
this.$post('/policy/findAll/',{page:1,size:10,params:{}})
// ③  request
this.$request({
    url: '/policy/findAll/',
    method: 'post',
    data: {page:1,size:10,params:{}}
})

2.2 兼容老框架的api分离式调用

本框架推荐使用五 2.1的方式调用，但是也兼容了老框架的api分离式调用，用于提取可复用的公共请求。
公共请求的api文件，统一放在@/api/*.js管理。
【请求示例】

/**
 * @/api/index.js
 */ 
import request from '@/utils/request'
export function getPageList(data) {
    return request.post('/policy/findAll', data)
}
/**
 * @/pages/index.vue
 */ 
import { getPageList } from "@/api/index.js"
export default {
    fetch() {
        return this.getPageList(this.pageDto)
    },
    methods: {
        getPageList(pageDto) {
            return getPageList(pageDto).then(res => {
              this.pageList = res.data.result
            })
        }
    },
}

3. 其他注意事项

原则上，所有初始化渲染数据的请求，都要在服务端渲染函数（asyncData或fetch）中进行，极个别无法在服务端渲染的请求，可以在Vue的生命周期(created或mounted)中初始化；
服务端渲染的生命周期（即asyncData/fetch），不能使用任何浏览器专属的对像（如DOM对象），也就是document和window，以及window的各种对象和方法，例如setTimeout、setInterval、localStorage、sessionStorage等；
有上述需求的初始化逻辑，可以放到created或mounted中初始化。

【六、其他规范与Q&A】

1. 关于`pages`

本框架路由采用约定式路由，即不再使用route.js进行路由声明，而是由框架根据pages目录自动生成路由，详见路由
文件夹或者文件，如果以_开头，表示此为动态路由，可以传入不同参数，在组件内容，可以使用上下文或者this.$router取到路由参数；
- 例如: /pages/news/detail/_id.vue、/pages/news/detail/_id/index.vue
- 访问: http://domain.com/pages/news/detail/12345 （上述两种写法均为这一路径）

【注意】

① 使用_id.vue的写法，表示id为可选参数，即可以通过http://domain.com/pages/news/detail访问。如果要对id进行限制或验证，可以在组件内使用validate()验证；
② 使用/_id/index.vue的写法，表示id为必选参数，访问http://domain.com/pages/news/detail会报404。如果只要求id必填，而没有其他格式限制，可以使用此方式。
③ validate()验证示例

// return true表示验证通过，return false表示验证失败 404
validate({ params }) {
    return /^\d+$/.test(params.id)
},

2. 关于`plugins`

用于自定义框架所需的各种插件，声明插件后在nuxt.config.js中引入插件即可，类似于原框架main.js相关功能。详见插件
框架已有的插件包（具体用户参照各插件的顶部注释）：
- plugin.js用于全局引入各种npm包；
- global.js用于声明全局变量与全局方法；
- request.js实现了全局请求封装（对应@/utils/request.js）;
- filter.js实现了全局请求封装（对应@/utils/filter.js）;
- util.js实现了全局请求封装（对应@/utils/util.js）;
- all.client.js只在客户端引入，用于替代原框架中app.vue中的各种初始化操作；
其他插件可根据需要自行定义，*.js表示服务端客户端均导入；*.client.js表示仅在客户端导入；*.server.js表示只在服务端导入；

3. 关于`layout`

用于定义框架中的各种布局文件，可根据需要自行定义，详见布局与视图
默认视图为default.vue，默认所有页面都将调用；error.vue是错误视图，当页面出现问题时，自动调用；
其他视图，可根据需要自行定义，并在组件内部声明引用。
【组件调用示例】

export default {
    // 需要调用的视图名称，不写默认调用default.vue
    layout: 'onlyBody',
    data(){
      return {}
    }
}

4. 关于`components`

用于定义框架中的各种自定义组件，可根据需要自行定义。
自定义组件中的数据，一般应从页面传入，如果需要再组件内部获取数据，应该使用fetch（子组件中不支持asyncData）。
components中声明的各种组件，在使用时，无需import导入。直接使用组件名按需调用即可。
【使用示例】

<template>
  <div>
    // Header组件
    <Header />
  </div>
</template>

5. 关于`store`

store文件夹为Nuxt提供用于定义Vuex状态树的文件夹，详细文档参照：Vuex状态树。
此文件夹下面的xxx.js，分别表示一个模块，例如index.js对应$store.state.xxx，而user.js对应$store.state.user.xxx
本框架中store中模块的定义与普通Vue框架大体相同，只是Nuxt框架会自动引用Vuex并加载到构建配置重，无需我们自己new Vuex()
【使用示例】

/**
 * 【注意区别】
 * state mutations action不再是包裹在一个对象中，并在new Vuex()的时候传入。 而是分别作为单独模块使用export导出即可。
 */
export const state = () => ({
    counter: 0
})
export const mutations = {
    increment(state) {
        state.counter++
    }
}

6. 关于`middleware`

middleware是框架中用于声明中间件的文件夹，声明后在nuxt.config.js中配置中间件即可，详细文档参照：中间件。
@/middleware/router.js为已经升级声明好的路由守卫中间件，可替代原框架中router.beforeEach中的路由守卫功能；

7. 关于`modules`

用于自定义模块的文件夹，可以在模块中对Nuxt启动部署的各种声明周期设置监听，详细文档参照：模块。
@/modules/generator.ts实现了一个对静态化结束generate:done时进行监听并处理的示例。

const generator: any = function () {
    this.nuxt.hook('generate:done', (context: any) => {
        // TODO samething
    })
}
export default generator

类似this.nuxt.hook('generate:done',() => {})的Nuxt框架hooks还有很多，例如：ready、error、render:before、build:compile 等等……详细参见INTERNALS

8. 其他`Q&A`

1）每个页面，必须使用`head`设置`title`，必要时还需在详情页设置`description`。（！！！切记！！！）

export default {
    head() {
        return {
            // title必须设置！！！ 列表可以直接写“xxx列表”，详情页等有不同标题的，要用新闻标题、商品标题等作为title前缀。
            title: this.detail.title + '_新闻详情',
            meta: [
                // 详情页，需要设置不同的description。 this.$getDesc 为全局封装的从富文本中截取100字符的description
                { hid: 'description', name: 'description', content: this.$getDesc(this.detail.details) },
            ],
        }
    }
}

2）`pages`目录中的层级结构，务必按照功能梳理清楚，比如`“news（新闻）”`的列表、详情都要在一个文件夹中。

（！！！目录结构一旦确定，原则上不可再调整！！！）

3）框架中的其他重要文件之【`CSS`篇】！！

框架各种css文件，位于@/assets/css/中。框架推荐使用scss语言，使用"sass": "~1.32.13"进行编译；
common.scss 为全局公共CSS，请将全局样式表声明于此。或自行定义CSS文件，并在此文件中import导入；
font.scss 用于定义本框架各种字体、图标库等；
variables.scss 声明了框架的各种全局Scss变量，可以在所有页面使用。
- 注意：全局主题色，请用$mainColor表示，不要在各自文件中自行声明！
element-variables.scss 是ElementUI的主题声明文件，如需全局调整ElementUI的配色，请在此调整；

小仙男·言在前

【一、框架概述】

1、框架介绍

2、开发环境

3、分支要求

3、关于本文档

【二、启动与部署】

【三、框架结构】

【四、生命周期】

几点说明：

1. 数据请求钩子

1.1 钩子相关说明

1.2 asyncData

1.3 fetch

2. 数据请求方式

2.1 【框架推荐】 使用vue实例直接调用

2.2 兼容老框架的api分离式调用

3. 其他注意事项

1. 关于pages

【注意】

2. 关于plugins

3. 关于layout

4. 关于components

5. 关于store

6. 关于middleware

7. 关于modules

1）每个页面，必须使用head设置title，必要时还需在详情页设置description。（！！！切记！！！）

2）pages目录中的层级结构，务必按照功能梳理清楚，比如“news（新闻）”的列表、详情都要在一个文件夹中。

3）框架中的其他重要文件之【CSS篇】！！

4）（未完待续…）其他任何框架问题，详询小仙男

2.1 【框架推荐】使用vue实例直接调用

1. 关于`pages`

2. 关于`plugins`

3. 关于`layout`

4. 关于`components`

5. 关于`store`

6. 关于`middleware`

7. 关于`modules`

1）每个页面，必须使用`head`设置`title`，必要时还需在详情页设置`description`。（！！！切记！！！）

2）`pages`目录中的层级结构，务必按照功能梳理清楚，比如`“news（新闻）”`的列表、详情都要在一个文件夹中。

3）框架中的其他重要文件之【`CSS`篇】！！