踩坑记录：nuxt3 - ssg 重构我的前端导航网站

一、💥 背景故事

不久前我利用周末搭建了个 万能导航网站，当时还写了篇文章：# 我给自己搭建的前端导航网站，你们都别用🤪。本来我以为不会有太大的访问量，主要是方便自己用。没想到用的人还不少（都有反骨，说不让用还用🤪）～

当时搭建的时候图快，没有考虑太多，直接用vite + vue3 + gitee pages快速部署了个项目。但是后面看有一定流量，所以也想推广一下。为了更好的 seo，所以打算用nuxt重构下。

nuxt好像已经出到3.6了吧，要用必须得用新的啊🙊就是网上可以参考的nuxt3的文章太少了… 所以我已经做好了踩坑的准备😭。
本文只分享一些涉及到的知识，因为没时间去深入研究，直接对着官方文档拿来用了～

nuxt重构版本很早就创建了，但是因为找房子和一些生活上的琐事，一直没时间弄，拖了这么久可算基本整完了，撒花撒花 🌼🌼🌼

二、🎁 重构成果

开门见山，直接贴出重构后的网址 前端助手
想查看旧网站的可以看这篇文章：# 我给自己搭建的前端导航网站，你们都别用🤪

重构后和旧站内容一模一样，只是多了个首页，以后可能会做一个好看的浏览器主页。下面贴一下目前网站的效果图：

图1-首页

图2-工具页

图3-文档页

图4-游戏页

图5-摸鱼页

图6-友情链接

三、🛠 项目搭建部署

重构第一步，先创建个项目部署好，搞好前期环境再着手页面搬家。

🕳 初始化项目需要科学上网，不然会报错，实在不行直接找个网上的模版下载下来。

npx nuxi init <project-name>

安装好依赖后，npm run dev项目跑起来看到下面的页面就说明初始化成功了。

因为我就个人开发，不用考虑什么规范性，像什么eslint，prettier，husky，lint-stage，commitlint 什么的我一概不装，讲究的就是一手快速搭建，节省时间～

项目创建好之后，怎么部署呢？
做了一点功课之后我本来打算用 vercel 部署，虽然之前没用过，但是真的是很简单，一键部署，导入项目后，任何构建命令都不需要配置，点击 deploy 就能部署好了～

但是在vercel部署后，我发现网站被墙了，还得科学上网才能访问，虽然我看到一些文章能够解决这个问题。但是我考虑到像 vercel, nelify 这种第三方平台，存在很大的不确定性因素，所以我放弃了在 vercel 上部署 ssr 项目的想法。

而且我这个网站全部都是静态页面，其实使用ssg就可以了。所以我最终决定在github pages上部署ssg站点。

🕳 一开始我连nuxt3怎么生成ssg都不知道，nuxt3的官方文档我感觉是真的乱，而且没有中文版，查起来真的费劲😖

生成ssg： npm run generate

执行 generate 命令后会在根目录下生成一个 dist 目录。那我寻思只要把master分支的dist目录重命名为docs，然后部署上去就得了呗，但是发现dist目录不是一个实际的文件夹，而是一个文件替身，它是一个地址链接，指向 .output/public 文件夹，并且我查找了很久nuxt3的配置文档，似乎无法修改 generate 生成的文件夹名😨。

🕳 研究怎么重命名dist目录浪费了我好多时间，网上关于“nuxt3 ssg项目如何部署到github pages”可以说一篇有用的文章都没有，看了几个文章不是重复就是完全就在乱讲。

最后我终于在 nuxt2 的文档里找到了部署方法😭（太坑了，用nuxt3还得查nuxt2的文档，不过这个方法应该不止适用于nuxt3，如果你之前部署过gitee pages，可能知道它）
这里我就不做搬运工作了，直接贴教程地址：
nuxt2文档，nuxt2文档中文版

四、部署后的问题

部署后我就开始项目重构工作了，我为了行文流畅，先把所有坑抛出来，最后再分享一些nuxt3的开发知识～

1. _nuxt/* 资源 404

重构后发现，打包生成的js、css文件全部404，但是查看 “gh-pages” 分支，这个文件确实是存在的，查阅资料后发现，这是因为触发了Github.io的 content-security-policy（内容安全策略），所以被禁止访问了。

content-security-policy说明

因为执行 generate 后生成的静态文件都在 _nuxt 目录下，它有特殊符号，我们只需要修改生成的静态文件夹名就能解决这个问题了，配置如下：

//nuxt.config.js
    app: {
        buildAssetsDir: 'static',   //修改站点资产的文件夹名称，默认是_nuxt
    }

2. _payload.json 文件 404

解决了js、css等静态文件404的问题后，发现有好多 _payload.json 文件也报404。

查阅配置文件后，找到了解决办法：

  experimental: {
    payloadExtraction: false   //启用此选项时（默认情况下）提取使用nuxt generate生成的页面的有效负载
  },

3. 图片 404

我们一般把图片放在assets文件夹中，同样也会构建到 _nuxt 文件夹，修改构建生成的文件夹名就可以解决这个问题。

🕳 但是我有的图片是动态加载的，vue项目常见的动态加载图片有以下几种：

• 直接用相对路径
• require()引入图片地址
• new URL(url, import.meta.url).href 动态引入静态资源

首先排除下面两种方法，require在nuxt3里不能用，new URL(url, import.meta.url).href 倒是能用，但是构建后文件地址会是本地的绝对路径，如下：

所以我想到的办法只能是用相对路径，将需要动态加载的图片都放到 public 文件夹下，这样图片也不会在构建的时候用hash值重命名。动态引入就直接写相对路径就行，如下：

const list = [{
  "icon": "../icons/1.png", 
  "name": "兼容性查询",
  "link": "https://caniuse.com/"
}]   

本来以为没问题了，但是部署之后又发现个奇怪的现象。刚刚打开页面的时候，图片还是404，只有刷新一下才会正常，观察发现，刚跳转到页面的时候，因为图片地址写的是相对路径，但是自动拼接的全路径是错误的，如下图：

最后无奈之下我只能将所有动态图片的地址都改为了线上地址，这样问题暂时得到了解决，图片加载都正常了（常用工具里的第3个‘json在线解析’的icon还是用的相对路径，大家可以看这个图调试下，如果有大佬分析出为什么刷新后才能正常显示了，请在评论区指教～🙏🙏🙏）

4. 部分页面需要全屏显示

像首页，友链页需要全屏显示，即不应用默认的全局布局。
layouts文件夹是存放页面布局组件的，其中default.vue是默认布局，只要页面没单独设置布局，都会显示默认布局，查阅后可以用 definePageMeta API设置布局，设置为false就可以不应用任何布局。

definePageMeta({
  layout: false,
});

5. 引入外部js

目前本站引入了3个外部js。

1. 全局引入不蒜子，用于网站数据统计

全局的配置都是在 nuxt.config.ts 里配置，查阅配置文档就行

app: {
    head: {
        script: [{ src: 'https//busuanzi.ibruce.info/busuanzi/2.3/busuanzi.pure.mini.js' }
        ]
    }
}

2. 某个页面引入jquery.js、fish.hs，实现底部鱼跳跃的动效

对某个页面的配置都可以用 useHead 等nuxt3 提供的 API 来配置。

useHead({
  script:[
      {
        type: 'text/javascript',
        src:'https://cdnjs.cloudflare.com/ajax/libs/jquery/3.1.1/jquery.min.js',
        body: true //<script>是否在body中
      },
      {
        type: 'text/javascript',
        src:'https://web-abin.gitee.io/abin-web/js/fish.js',
        body: true //<script>是否在body中
      },
  ]
})

五、快速上手

目录结构

├── app.vue # Nuxt 3 应用程序中的主组件 入口组件
├── components # 组件目录，支持自动导入
├── layouts # 布局目录
├── composables # 公共函数，支持自动导入
├── assets # 静态资源目录 与vue项目的assets相同
├── middleware # 路由中间件
├── nuxt.config.ts  # Nuxt 配置文件，可以理解成vue.config.js 文件名必须是nuxt.config 后缀名可以是.js,.ts或.mjs
├── package.json
├── pages # 基于文件的路由
├── plugins #插件
├── public # 不会参与打包，与vue项目的public类似直接挂在服务器的根目录
├── README.md
├── server 
├── tsconfig.json
└── yarn.lock

基础知识

关于nuxt3的基础知识我就不重复了，这里提供我看到的比较全面的两个文档：

1. # 超完整的Nuxt3踩坑实录，那真是泰裤辣！！
2. nuxt3 中文文档；

其他注意点

1. nuxt3里不能直接用window、document这种客户端的api，在使用前，要用process.client||process.server来判断环境，否则会报错。

if(process.client){
  window.localStorage.getItem('test')
}

2. nuxt3 内置自动导入，比如vue3 的ref,reactive,onmounted等这些api都不需要手动导入，约定目录下的文件也不需要导入，例如components文件夹下的组件，可以直接使用；

关闭自动导入：

//nuxt.config.ts
export default defineNuxtConfig({
  imports: {
    autoImport: false
  }
})

六、结语

其实nuxt3使用起来没有什么太大难度，相反，约定式的开发会提高不少开发效率。它的难点真正在于可供参考的文档太少，技术生态较差。所以很感谢那些技术先驱们，为大部分普通的程序员趟平了路 💖💖💖。

另外，我后面以后快重构完成了，才发现这个 nuxt3 中文文档，查阅起来是真的很清晰，推荐给大家：
https://ezdoc.cn/docs/nuxtjs/nuxt-config

网站传送门： 前端助手

我是喜欢归纳总结前端相关知识的前端阿彬，尽力持续输出原创优质文章，欢迎点赞关注😘

往期文章：
# 🧙‍♀️css魔法：伪元素content ➕ css函数
# 玩转css逐帧动画，纯css让哥哥动起来💃
# 🕸2023 前端 SEO 无死角解读
# 我给自己搭建的前端导航网站，你们都别用🤪
# 2023 最新最细 vite+vue3+ts 多页面项目架构，建议收藏备用！
# 浅谈 强制缓存/协商缓存 怎么用？
# 2023 前端性能优化清单