更新日志

2020-11-25 完成进度60%

  1. 完成图标设计及manifest生成配置图文教程。
  2. 完成hexo-offline-popup教程。

2020-11-26 v1.0

  1. 完成workbox教程,修改了主题文档的更新通知引入方式,更符合原生主题体验。
  2. 完成Gulp教程。
  3. 经典bug归纳。

2021-01-16 v1.01

  1. 修复workbox的gulpfile.js的bug。
  2. 感谢@Nesxc的反馈。

2021-01-18 v1.02

  1. 修复了关于manifest.json必要项的描述。必须填写start_url才能看到地址栏的安装按钮。
  2. 恭喜@Nesxc双杀。

2021-02-01 v1.03

  1. 更新了butterfly_v3.6.1的适配提示

写在最前

PWA的全称是Progressive Web Apps,译为渐进式网络应用程序。装配了PWA以后,用户可以将网站作为WEB APP安装到自己的设备上,以原生应用般的方式浏览博客,同时借助PWA的缓存机制,能够更快速的浏览。本文讨论的是使用两种方案实现PWA。最终效果不尽相同,但是都可以实现原生应用体验和更新弹窗提示。其实还有个离线博客,但是视方案不同会有很多BUG,而且离线博客意义何在啊!

图标设计

在使用PWA之前,我们最好先行设计一个符合网站主题的图标。
本站使用的是brandmark图标设计网站,访问 brandmark进行图标设计。下载需要收费,不过可以截图。建议截图的时候截成正方形。

图文教程

输入主标题和副标题
添加网页元素作为风格设计线索
选择适合自己网站的配色方案
下载需要收费,但是可以截图

生成图标包及manifest

因为我们最终目的是要制作一个全平台的WEB APP,所以对于图标的大小、类型适配显得格外重要。可以访问realfavicongenerator进行图标制作及manifest的生成。

图文教程

选择图片
创建所有图标
调整Windows磁贴图标配色
设置图片相对于source目录的存放路径
设置Web App名称
生成README.md
选择生成
下载资源包
获取图标文件和manifest

配置PWA

实现PWA的方式有许多种,本帖基于Butterfly主题文档进行详细拓展,所以只讨论两种方案。

  1. 使用hexo-offline-popup:这个插件配置较为简单,安装以后添加几行配置项即可。适合初学者。
  2. 使用workbox:这个插件需要配合gulp插件,所以配置较为繁琐,好处是可以自定义适配弹窗提示,适合对前端有一定了解的用户。如果你还有使用pjax,恭喜你,BUG御三家马上就可以集齐了。
  1. 在博客根目录[Blogroot]下打开终端,输入以下指令安装hexo-offline-popup插件。

    npm install hexo-offline-popup --save
  2. 修改站点配置文件[Blogroot]/_config.yml,在站点配置文件_config.yml中增加以下内容:
    # hexo-offline-popup.
    service_worker:
    maximumFileSizeToCacheInBytes: 3145728 # 缓存的最大文件大小,以字节为单位,此处设置为3MB。
    staticFileGlobs:
    - public/**/*.{js,html,xml,css,png,jpg,gif,svg,webp,eot,ttf,woff,woff2}
    # - public/**/*.{html,xml} #精简版使用这行即可
    # 静态文件合集,如果你的站点使用了例如webp格式的文件,请将文件类型添加进去。。
    # 注意,此处的文件类型就是会缓存下来的所有文件类型,如果不需要缓存那么多,
    # 而只是想判断网页更新与否,缓存html和xml即可。
    stripPrefix: public
    verbose: false
    runtimeCaching:
    # CDNs - should be cacheFirst, since they should be used specific versions so should not change
    - urlPattern: /* # 如果你需要加载CDN資源,请配置该选项,如果沒有,可以不配置。
    handler: cacheFirst
    options:
    origin: unpkg.com # 又拍云
    - urlPattern: /*
    handler: cacheFirst
    options:
    origin: cdn.jsdelivr.net # jsdelivr
    # 更多cdn可自行参照上述格式进行配置。
  3. 将之前生成的图标包移入相应的目录,例如我是/img/siteicon/,所以放到[Blogroot]/source/img/siteicon/目录下。

  4. 打开图标包内的site.webmanifest,建议修改文件名为manifest.json并将其放到[Blogroot]/source目录下,以下是我的manifest.json配置内容,其中的theme_color建议用取色器取设计的图标的主色调,同时务必配置start_url和name的配置项,这关系到你之后能否看到浏览器的应用安装按钮。:

    {   "lang": "en",
    "dir": "ltr",
    "name": "Akilarの糖果屋",
    "description": "Akilar.top",
    "display": "standalone",
    "short_name": "Aki~",
    "scope": "/",
    "start_url": "/",
    "icons": [
    {
    "src": "/img/siteicon/android-chrome-36x36.png",
    "sizes": "36x36",
    "type": "image/png"
    },
    {
    "src": "/img/siteicon/android-chrome-48x48.png",
    "sizes": "48x48",
    "type": "image/png"
    },
    {
    "src": "/img/siteicon/android-chrome-72x72.png",
    "sizes": "72x72",
    "type": "image/png"
    },
    {
    "src": "/img/siteicon/android-chrome-96x96.png",
    "sizes": "96x96",
    "type": "image/png"
    },
    {
    "src": "/img/siteicon/android-chrome-144x144.png",
    "sizes": "144x144",
    "type": "image/png"
    },
    {
    "src": "/img/siteicon/android-chrome-192x192.png",
    "sizes": "192x192",
    "type": "image/png"
    },
    {
    "src": "/img/siteicon/android-chrome-256x256.png",
    "sizes": "256x256",
    "type": "image/png"
    },
    {
    "src": "/img/siteicon/android-chrome-384x384.png",
    "sizes": "384x384",
    "type": "image/png"
    },
    {
    "src": "/img/siteicon/android-chrome-512x512.png",
    "sizes": "512x512",
    "type": "image/png"
    }
    ],
    "theme_color": "#212121",
    "background_color": "#212121",
    "display": "standalone"
    }

    json中不要添加任何注释,不然会报错。注意最后一条内容后面不用加逗号”,” 。

  5. 打开主题配置文件[Blogroot]/_config.butterfly.yml,找到PWA配置项。添加图标路径。这里的theme_color建议改成你图标的主色调,包括manifest.json中的theme_color也是如此。

    # PWA
    pwa:
    enable: true
    manifest: /manifest.json
    theme_color: '#212121'
    apple_touch_icon: /img/siteicon/apple-touch-icon.png
    favicon_32_32: /img/siteicon/favicon-32x32.png
    favicon_16_16: /img/siteicon/favicon-16x16.png
    mask_icon: /img/siteicon/safari-pinned-tab.svg
  6. 运行hexo clean之后hexo generate,使用hexo server本地查看或者hexo deploy部署到网站上。可以通过Chrome插件Lighthouse检查PWA配置是否生效以及配置是否正确。在Chrome浏览器中打开站点,按F12打开控制台,在右上角找到Lighthouse,可能没显示出来,在>>里找找。

  7. 使用hexo-offline-popup以后,如果还开启了pjax,可能遇到页面URL带着长长的后缀。形似index.html?_sw-precache=fff6559539ab8f2d6043bcfa832ce38f。此处感谢Android(矩阵)大佬提供的方案,把以下js引入即可,实质是劫持了pjax,并对其链接进行重定向:

    //重定向浏览器地址
    pjax.site_handleResponse = pjax.handleResponse;
    pjax.handleResponse = function(responseText, request, href, options){
    Object.defineProperty(request,'responseURL',{
    value: href
    });
    pjax.site_handleResponse(responseText,request,href,options);
    }

    而workbox是通过设置 directoryIndex:null来去掉index.html的。这会导致PWA无法加载索引文件,也就是说无法从PWA加载index.html,最终影响离线观看博客的体验。

  1. 安装必要插件
    既然要使用gulp配合workbox实现PWA,自然少不了安装这两个插件。
    npm install --global gulp-cli # 全局安装gulp命令集
    npm install workbox-build gulp --save # 安装workbox和gulp插件
  2. 创建gulpfile.js
    在Hexo的根目录,创建一个gulpfile.js文件,打开[Blogroot]/gulpfile.js,
    输入

    const gulp = require("gulp");
    const workbox = require("workbox-build");

    gulp.task('generate-service-worker', () => {
    return workbox.injectManifest({
    swSrc: './sw-template.js',
    swDest: './public/sw.js',
    globDirectory: './public',
    globPatterns: [
    "**/*.{html,css,js,json,woff2,xml}"
    // "**/*.{html,xml}"
    //精简版使用下面这行
    ],
    modifyURLPrefix: {
    "": "./"
    }
    });
    });
    gulp.task("default", gulp.series("generate-service-worker"));
  3. 创建在Hexo的根目录,创建一个sw-template.js文件,打开[Blogroot]/sw-template.js,输入以下内容:

    const workboxVersion = '5.1.3';

    importScripts(`https://storage.googleapis.com/workbox-cdn/releases/${workboxVersion}/workbox-sw.js`);

    workbox.core.setCacheNameDetails({
    prefix: "your name"
    });

    workbox.core.skipWaiting();

    workbox.core.clientsClaim();

    workbox.precaching.precacheAndRoute(self.__WB_MANIFEST,{
    directoryIndex: null
    });

    workbox.precaching.cleanupOutdatedCaches();
    // 可选内容 start 都选可能造成缓存过多 酌情保留。
    // 图片资源
    workbox.routing.registerRoute(
    /\.(?:png|jpg|jpeg|gif|bmp|webp|svg|ico)$/,
    new workbox.strategies.CacheFirst({
    cacheName: "images",
    plugins: [
    new workbox.expiration.ExpirationPlugin({
    maxEntries: 1000,
    maxAgeSeconds: 60 * 60 * 24 * 30
    }),
    new workbox.cacheableResponse.CacheableResponsePlugin({
    statuses: [0, 200]
    })
    ]
    })
    );

    // 字体文件
    workbox.routing.registerRoute(
    /\.(?:eot|ttf|woff|woff2)$/,
    new workbox.strategies.CacheFirst({
    cacheName: "fonts",
    plugins: [
    new workbox.expiration.ExpirationPlugin({
    maxEntries: 1000,
    maxAgeSeconds: 60 * 60 * 24 * 30
    }),
    new workbox.cacheableResponse.CacheableResponsePlugin({
    statuses: [0, 200]
    })
    ]
    })
    );

    // 谷歌字体
    workbox.routing.registerRoute(
    /^https:\/\/fonts\.googleapis\.com/,
    new workbox.strategies.StaleWhileRevalidate({
    cacheName: "google-fonts-stylesheets"
    })
    );
    workbox.routing.registerRoute(
    /^https:\/\/fonts\.gstatic\.com/,
    new workbox.strategies.CacheFirst({
    cacheName: 'google-fonts-webfonts',
    plugins: [
    new workbox.expiration.ExpirationPlugin({
    maxEntries: 1000,
    maxAgeSeconds: 60 * 60 * 24 * 30
    }),
    new workbox.cacheableResponse.CacheableResponsePlugin({
    statuses: [0, 200]
    })
    ]
    })
    );

    // jsdelivr的CDN资源
    workbox.routing.registerRoute(
    /^https:\/\/cdn\.jsdelivr\.net/,
    new workbox.strategies.CacheFirst({
    cacheName: "static-libs",
    plugins: [
    new workbox.expiration.ExpirationPlugin({
    maxEntries: 1000,
    maxAgeSeconds: 60 * 60 * 24 * 30
    }),
    new workbox.cacheableResponse.CacheableResponsePlugin({
    statuses: [0, 200]
    })
    ]
    })
    );
    // 可选内容 end 都选可能造成缓存过多 酌情保留。
    workbox.googleAnalytics.initialize();
  4. [Blogroot]\themes\butterfly\layout\includes\third-party\目录下新建pwanotice.pug文件,
    打开[Blogroot]\themes\butterfly\layout\includes\third-party\pwanotice.pug,输入:

    #app-refresh.app-refresh(style='position: fixed;top: -2.2rem;left: 0;right: 0;z-index: 99999;padding: 0 1rem;font-size: 15px;height: 2.2rem;transition: all 0.3s ease;')
    .app-refresh-wrap(style=' display: flex;color: #fff;height: 100%;align-items: center;justify-content: center;')
    label ✨ 糖果屋上新啦! 👉
    a(href='javascript:void(0)' onclick='location.reload()')
    span(style='color: #fff;text-decoration: underline;cursor: pointer;') 🍭查看新品🍬
    script.
    if ('serviceWorker' in navigator) {
    if (navigator.serviceWorker.controller) {
    navigator.serviceWorker.addEventListener('controllerchange', function() {
    showNotification()
    })
    }
    window.addEventListener('load', function() {
    navigator.serviceWorker.register('/sw.js')
    })
    }
    function showNotification() {
    if (GLOBAL_CONFIG.Snackbar) {
    var snackbarBg =
    document.documentElement.getAttribute('data-theme') === 'light' ?
    GLOBAL_CONFIG.Snackbar.bgLight :
    GLOBAL_CONFIG.Snackbar.bgDark
    var snackbarPos = GLOBAL_CONFIG.Snackbar.position
    Snackbar.show({
    text: '✨ 糖果屋上新啦! 👉',
    backgroundColor: snackbarBg,
    duration: 500000,
    pos: snackbarPos,
    actionText: '🍭查看新品🍬',
    actionTextColor: '#fff',
    onActionClick: function(e) {
    location.reload()
    },
    })
    } else {
    var showBg =
    document.documentElement.getAttribute('data-theme') === 'light' ?
    '#49b1f5' :
    '#1f1f1f'
    var cssText = `top: 0; background: ${showBg};`
    document.getElementById('app-refresh').style.cssText = cssText
    }
    }
  5. 修改[Blogroot]\themes\butterfly\layout\includes\additional-js.pug,在文件底部添加以下内容,注意缩进。butterfly_v3.6.0取消了缓存配置,转为完全默认,需要将{cache:theme.fragment_cache}改为{cache: true}:

          if theme.pjax.enable
    !=partial('includes/third-party/pjax', {}, {cache:theme.fragment_cache})

    !=partial('includes/third-party/baidu_push', {}, {cache:theme.fragment_cache})

    + if theme.pwa.enable
    + !=partial('includes/third-party/pwanotice', {}, {cache:theme.fragment_cache})
  6. 将之前生成的图标包移入相应的目录,例如我是/img/siteicon/,所以放到[Blogroot]/source/img/siteicon/目录下。

  7. 打开图标包内的site.webmanifest,建议修改文件名为manifest.json并将其放到[Blogroot]/source目录下,以下是我的manifest.json配置内容,其中的theme_color建议用取色器取设计的图标的主色调,同时务必配置start_url和name的配置项,这关系到你之后能否看到浏览器的应用安装按钮。:

    {   "lang": "en",
    "dir": "ltr",
    "name": "Akilarの糖果屋",
    "description": "Akilar.top",
    "display": "standalone",
    "short_name": "Aki~",
    "scope": "/",
    "start_url": "/",
    "icons": [
    {
    "src": "/img/siteicon/android-chrome-36x36.png",
    "sizes": "36x36",
    "type": "image/png"
    },
    {
    "src": "/img/siteicon/android-chrome-48x48.png",
    "sizes": "48x48",
    "type": "image/png"
    },
    {
    "src": "/img/siteicon/android-chrome-72x72.png",
    "sizes": "72x72",
    "type": "image/png"
    },
    {
    "src": "/img/siteicon/android-chrome-96x96.png",
    "sizes": "96x96",
    "type": "image/png"
    },
    {
    "src": "/img/siteicon/android-chrome-144x144.png",
    "sizes": "144x144",
    "type": "image/png"
    },
    {
    "src": "/img/siteicon/android-chrome-192x192.png",
    "sizes": "192x192",
    "type": "image/png"
    },
    {
    "src": "/img/siteicon/android-chrome-256x256.png",
    "sizes": "256x256",
    "type": "image/png"
    },
    {
    "src": "/img/siteicon/android-chrome-384x384.png",
    "sizes": "384x384",
    "type": "image/png"
    },
    {
    "src": "/img/siteicon/android-chrome-512x512.png",
    "sizes": "512x512",
    "type": "image/png"
    }
    ],
    "theme_color": "#212121",
    "background_color": "#212121",
    "display": "standalone"
    }

    json中不要添加任何注释,不然会报错。注意最后一条内容后面不用加逗号”,” 。

  8. 打开主题配置文件[Blogroot]/_config.butterfly.yml,找到PWA配置项。添加图标路径。这里的theme_color建议改成你图标的主色调,包括manifest.json中的theme_color也是如此。

    # PWA
    pwa:
    enable: true
    manifest: /manifest.json
    theme_color: '#212121'
    apple_touch_icon: /img/siteicon/apple-touch-icon.png
    favicon_32_32: /img/siteicon/favicon-32x32.png
    favicon_16_16: /img/siteicon/favicon-16x16.png
    mask_icon: /img/siteicon/safari-pinned-tab.svg
  9. 运行以下指令

    hexo clean # 清空缓存
    hexo generate # 重新编译生成页面
    gulp # hexo g之后必须运行gulp指令,不然PWA不会生效
    hexo server # 打开本地预览
    hexo deploy # 部署到网站上查看

    运行hexo g之后必须运行gulp指令,不然PWA不会生效!

    可以通过Chrome插件Lighthouse检查PWA配置是否生效以及配置是否正确。在Chrome浏览器中打开站点,按F12打开控制台,在右上角找到Lighthouse,可能没显示出来,在>>里找找。

拓展内容,使用GULP压缩静态资源

既然已经装了gulp了,干脆把gulp也配置好吧。

都说了是BUG御三家了,用不用取决于你的个人意志哦,现在回头用hexo-offline-popup还来得及。

  1. 安装全套压缩插件
    # 压缩html插件
    npm install gulp-htmlclean --save-dev
    npm install --save gulp-htmlmin
    # 压缩css插件
    npm install gulp-clean-css --save-dev
    # 压缩js插件
    npm install --save-dev gulp-uglify
    npm install --save-dev gulp-babel @babel/core @babel/preset-env
    # 压缩图片插件
    npm install --save-dev gulp-imagemin
  2. [Blogroot]/gulpfile.js里的内容修改为:

    var gulp = require('gulp');
    var cleanCSS = require('gulp-clean-css');
    var htmlmin = require('gulp-htmlmin');
    var htmlclean = require('gulp-htmlclean');
    var imagemin = require('gulp-imagemin');
    var workbox = require("workbox-build");
    // babel
    var uglify = require('gulp-uglify');
    var babel = require('gulp-babel');

    //pwa
    gulp.task('generate-service-worker', () => {
    return workbox.injectManifest({
    swSrc: './sw-template.js',
    swDest: './public/sw.js',
    globDirectory: './public',
    globPatterns: [
    "**/*.{html,css,js,json,woff2,xml}"
    ],
    modifyURLPrefix: {
    "": "./"
    }
    });
    });

    //minify js babel
    gulp.task('compress', () =>
    gulp.src(['./public/**/*.js', '!./public/**/*.min.js'])
    .pipe(babel({
    presets: ['@babel/preset-env']
    }))
    .pipe(uglify().on('error', function(e){
    console.log(e);
    }))
    .pipe(gulp.dest('./public'))
    );

    //css
    gulp.task('minify-css', () => {
    return gulp.src('./public/**/*.css')
    .pipe(cleanCSS({
    compatibility: 'ie11'
    }))
    .pipe(gulp.dest('./public'));
    });


    // 壓縮 public 目錄內 html
    gulp.task('minify-html', () => {
    return gulp.src('./public/**/*.html')
    .pipe(htmlclean())
    .pipe(htmlmin({
    removeComments: true, //清除 HTML 註釋
    collapseWhitespace: true, //壓縮 HTML
    collapseBooleanAttributes: true, //省略布爾屬性的值 <input checked="true"/> ==> <input />
    removeEmptyAttributes: true, //刪除所有空格作屬性值 <input id="" /> ==> <input />
    removeScriptTypeAttributes: true, //刪除 <script> 的 type="text/javascript"
    removeStyleLinkTypeAttributes: true, //刪除 <style> 和 <link> 的 type="text/css"
    minifyJS: true, //壓縮頁面 JS
    minifyCSS: true, //壓縮頁面 CSS
    minifyURLs: true
    }))
    .pipe(gulp.dest('./public'))
    });

    // 壓縮 public/uploads 目錄內圖片
    gulp.task('minify-images', async () => {
    gulp.src('./public/img/**/*.*')
    .pipe(imagemin({
    optimizationLevel: 5, //類型:Number 預設:3 取值範圍:0-7(優化等級)
    progressive: true, //類型:Boolean 預設:false 無失真壓縮jpg圖片
    interlaced: false, //類型:Boolean 預設:false 隔行掃描gif進行渲染
    multipass: false, //類型:Boolean 預設:false 多次優化svg直到完全優化
    }))
    .pipe(gulp.dest('./public/img'));
    });

    // 執行 gulp 命令時執行的任務
    gulp.task("default", gulp.series("generate-service-worker", gulp.parallel(
    'compress','minify-html', 'minify-css', 'minify-images'
    )));
  3. 使用了gulp压缩js以后,使用了冰卡诺老师的gitcalendar和本站的右键环形菜单教程的用户,会发现gitcalendar右键菜单失效。原因是js加密压缩的算法存在问题。建议直接屏蔽对这两个js的压缩。修改[Blogroot]/gulpfile.js,添加屏蔽项。
          //minify js babel
    gulp.task('compress', () =>
    - gulp.src(['./public/**/*.js', '!./public/**/*.min.js'])
    + gulp.src(['./public/**/*.js', '!./public/**/*.min.js','!./public/js/custom/galmenu.js','!./public/js/custom/gitcalendar.js'])
    .pipe(babel({
    presets: ['@babel/preset-env']
    }))
    .pipe(uglify().on('error', function(e){
    console.log(e);
    }))
    .pipe(gulp.dest('./public'))
    );
  4. 运行gulp指令时报错:

    gulp-imagemin: Couldn't load default plugin "gifsicle"
    gulp-imagemin: Couldn't load default plugin "optipng"

    这个众说纷纭,一个是说插件安装不对,一个是说和nvm版本不兼容,通过github action使用CI安装时并不会报这个错,推测是nvm版本不兼容。
    事实上这个只是作用于图片压缩,一般也就节省个5kB,而且这个报错不影响网站部署,可以无视。压缩图片还是得靠imagine