ant-h5ng-plugin

v1.0.0

Published

6 months ago

H5NG是蚂蚁国际客户端团队研发的一款轻量化容器（拥有类似PWA中的资源离线化能力）该插件主要用于生成各种前端工程打包产物对应的 manifest.json

Downloads

0High
0Medium
0Low

marmot.antgroup

H5NG 前端插件

简介

H5NG（H5 Next Generation）是蚂蚁国际客户端团队研发的一款轻量化容器（拥有类似PWA中的资源离线化能力）
H5NG 前端插件( h5ng-plugin )是一个根据用户配置和 html 的资源引用，对项目打包产物分析生成对应 manifest.json 的插件，与 H5NG 一起提供给客户使用。

html 资源引用示例

<html>

<head>
  <script src="common.min.0.6.2.2b6eb541.js"></script>
  <link href="common.c707d03d.css" rel="stylesheet">
  <link href="index.eb68b29e.css" rel="stylesheet">
</head>

</html>

manifest.json 生成示例

{
  "name": "index.html",
  "version": "1.1.1",
  "offlineResources": {
    "sync": [
    	// 上述 html 资源引用
      "https://prod.staticUrlPrefix.com/common.min.0.6.2.2b6eb541.js",
      "https://prod.staticUrlPrefix.com/common.c707d03d.css",
      "https://prod.staticUrlPrefix.com/index.eb68b29e.css",
    ],
    "async": [
        "https://prod.staticUrlPrefix.com/async/index.js"
    ]
  },
  "linkPages": [
    "https://prod.htmlUrl.com/xxx/xxx/xxxxxx",
    "https://prod.htmlUrl.com/other.html"
  ]
}

使用

h5ng-plugin 提供两种使用方式：

全局命令行
项目构建处理插件

全局命令行

安装

// 全局安装
$ npm i ant-h5ng-plugin@latest -g

安装结束后可以使用 h5ng -v 检查安装是否成功

$ h5ng -V

v0.0.0

命令

h5ng-plugin 提供了下列命令：

| 命令 | 使用 | 描述 | | --- | --- | --- | | h5ng generate | h5ng generate [options] | 生成 manifest.json |

options

h5ng-plugin 提供了以下选项：

| 选项/别名 | 描述 | | --- | --- | | -cli | 根据命令行交互数据配置生成 manifest.json | | -config | 根据 h5ng.config.ts 配置生成 manifest.json 建议作为项目构建插件使用 | | -V, --version | 显示版本信息 | | -h, --help | 显示帮助菜单 |

-cli 命令行交互选项说明

h5ng generate -cli 命令行交互选项

$ h5ng generate -cli

// 项目打包后, css、js 等资源在部署后的域名路径前缀
$ ? 请输入部署后资源路径前缀(eg: https://xxx/*) 

// 项目打包后, html 文件在部署后的域名路径前缀
$ ? 请输入部署后html路径前缀(eg: https://xxx/*) 

// manifest.json 文件的版本号,客户端容器不消费,仅作前端内部记录
$ ? 请输入生成的 manifest 版本号(eg: 0.0.1) 

// 项目的打包目录路径,如果为空则会依次按照 dist、bundle、build 文件夹寻找
$ ? 请输入打包目录路径(eg: /dist) 

// 是否需要排除项（排除项内不处理生成 html 对应的 manifest.json ）
$ ? 是否需要 exclude 配置 (y/N)

// 忽略项目录路径
$ ? 请输入 exclude 目录路径(eg: /dist) 

// 如果希望排除上一步输入的整个目录,则此项不填；如果希望排除上一步输入目录下的某个 html 文件,则输入对应 html 的名称,支持字符串形式的正则
$ ? 请输入 exclude 目录下 html 文件名(仅当指定 exclude 为目录下html文件时填写,支持正则, eg: index.html$)

// 如需继续增加排出项可输入y,否则输入N
$ ? 是否继续增加 exclude 配置 (y/N)

命令行交互结束，开始根据输入数据，对打包目录中 html 文件进行引用分析，生成 manifest.json 效果可参考简介

项目构建处理插件

安装

// 项目内安装
$ npm i ant-h5ng-plugin@latest -D

项目接入处理

项目本身需要在 build 命令加入串行命令 h5ng generate -config

"scripts": {
  - "build": "father build",
  + "build": "father build && h5ng generate -config",
}

配置文件说明

version

类型: string
默认值: '0.0.0-local'

生成的 manifest.json 的版本号客户端容器不消费，仅作前端内部记录

outputPath

类型: string
默认值: /dist,/bundle,/build

打包输出目录，如果没有则依次寻找 /dist, /bundle, /build

staticUrlPrefix

类型: string | {DEV?:string,TEST?:string,PRE?:string,PROD?:string}
- 采用后者根据环境配置 url，需要构建时注入 process.env.STAGE_NAME ，默认 PROD
默认值(占位值): '{{__RENDER_STATIC_URL_PREFIX__}}'

项目打包后, css、js 等资源在部署后的域名路径前缀

htmlUrlPrefix

类型: string | {DEV?:string,TEST?:string,PRE?:string,PROD?:string}
采用后者根据环境配置 url ，需要构建时注入 process.env.STAGE_NAME ，默认 PROD
默认值(占位值): process.env.DYNAMIC_PUBLIC_URL || '{{__RENDER_PACK_ORIGIN_URL__}}'

项目打包后, html 文件在部署后的域名路径前缀

pages

类型： array
- html
  - 类型： object
  - 默认值: 无

{
  // html 文件路径
  path: "/build",
  // html 文件名,字符串或正则规则
  name: "index.html",
}

config
- 类型： object
- 默认值: 无

// 页面的配置信息
{
  // 离线资源
  offlineResources: {
    // 异步资源
    async: [
      // 三种形式
      
      // 1、现有资源绝对路径 url ,直接合并进入引用
      "https://prod.staticUrlPrefix.com/4.6.9/index.js",
      
      // 2、基于部署域名的路径,处理后会拼接上部署域名前缀
      "/4.6.9/index.js",
      
      // 3、项目自身资源（打包后部署资源）,提供目录路径、名称
      // eg: /build/index.2cc034b0.js, /build/index.3a2f49fa.css
      {
        // 资源在打包目录中的目录名(不处理子目录)
        path: "/build",
        // 资源名,字符串或正则规则
        name: new RegExp("index.(\\S+).(js|css)$"),
        // name: /index.(\S+).(js|css)$/ ,
      },
    ],
    // 同步资源,形式同上
    sync: [],
  },
  // 关联页面
  linkPages: [
    // 三种形式
    
    // 1、现有页面绝对路径,直接合并进入引用
    "https://prod.htmlUrl.com/page/sub",
    
    // 2、基于 html 部署域名的路径,处理后会拼接上部署域名前缀
    "/page/sub",
    
    // 3、(不推荐)项目自身资源（打包后部署资源）,提供目录路径、名称
    // eg: /build/index.html,
    {
      // html在打包目录中的目录名(不处理子目录)
      path: "/build",
      //字符串或正则规则
      name: /index.html$/,
    },
  ],
};

默认值：[]

各html自定义配置，用户可在这里人为配置打包目录中个 html 的引用 h5ng-plugin 会自动分析 html 自身的资源引用并写入 manifest.json ，这些引用不需要写入 pages 对应页面的配置中，pages 项可认为是人为指定对应 html 的额外引用。

common

类型： array , 配置项同 pages.config
默认值：[]

各html公共配置，每个 html 被处理后均包含此项指定的引用

exclude

类型： array
默认值：[]

忽略处理项，指定的目录和 html 文件将不处理，包含子目录

// 两种形式
[
  // 1、忽略目录下对应的 html（包含子目录）
  // eg: /build/xxx.index.html
  {
    path: "/build",
    //字符串或正则规则
    name: /index.html$/,
  },
  // 2、忽略整个目录（包含子目录）
  // eg: /build/abc/*
  {
    path: "/build/abc",
  },
];

include

类型： array
默认值：[]

指定处理项，只处理此项指定的内容，包含子目录，形式同 exclude 此项为空时将处理 exclude 项外打包目录内所有的 html

配置文件&对应结果示例

import { defineH5NGConfig } from "ant-h5ng-plugin";

export default defineH5NGConfig({
  version: "1.1.1",
  outputPath: "/build",
  // 项目打包后, css、js 等资源在部署后的域名路径前缀
  staticUrlPrefix: {
    DEV: "https://dev.staticUrlPrefix.com",
    TEST: "https://test.staticUrlPrefix.com",
    PRE: "https://pre.staticUrlPrefix.com",
    PROD: "https://prod.staticUrlPrefix.com",
  },
  // 项目打包后, html 文件在部署后的域名路径前缀
  htmlUrlPrefix: {
    DEV: "https://dev.htmlUrl.com",
    TEST: "https://test.htmlUrl.com",
    PRE: "https://pre.htmlUrl.com",
    PROD: "https://prod.htmlUrl.com",
  },
  common: {
    offlineResources: {
      sync: [],
      async: [
        "https://prod.staticUrlPrefix.com/async/index.js"
      ],
    },
    linkPages: [],
  },

  // 各个页面的资源
  pages: [
    {
      html: {
        path: "/build",
        name: "index.html",
      },
      // 页面的配置信息
      config: {
        offlineResources: {
          async: [],
          sync: [
            "https://prod.staticUrlPrefix.com/sync/index.js",
            "/sync/index.css",
            {
              path: "/build",
              name: new RegExp("index.(\\S+).(js|css)$"),
            },
          ],
        },
        linkPages: [
          "https://prod.htmlUrl.com/xxx/xxx/xxxxxx",
          "/other.html"
        ],
      },
    },
  ],
  exclude: [
    {
      path: "/build",
      name: /other.html$/,
    },
    {
      path: "/build/a/b",
    },
  ],
  include: [
    {
      path: "/build/",
      name: /index.html$/,
    },
    {
      path: "/build/a",
    },
  ],
});

.
├── build
│   ├── index.3k33fk42.js
│   ├── index.3k33fk42.css
│   ├── index.html（指定文件处理）
│   ├── other.html（文件忽略）
│   ├── a（指定目录处理）
│   │   └── b（目录忽略）
└── h5ng.config.ts

{
  "name": "index.html",
  "version": "1.1.1",
  "offlineResources": {
    "sync": [
      "https://prod.staticUrlPrefix.com/sync/index.js",
      "https://prod.staticUrlPrefix.com/sync/index.css",
      "https://prod.staticUrlPrefix.com/index.3k33fk42.js",
      "https://prod.staticUrlPrefix.com/index.3k33fk42.css",
    ],
    "async": [
        "https://prod.staticUrlPrefix.com/async/index.js"
    ]
  },
  "linkPages": [
    "https://prod.htmlUrl.com/xxx/xxx/xxxxxx",
    "https://prod.htmlUrl.com/other.html"
  ]
}