qingtui-h5package-sdk 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 轻推团队
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# qingtui-h5package-sdk
+
+
+## 安装
+
+```bash
+npm install qingtui-h5package-sdk --save-dev
+```
+
+
+## 快速开始
+
+1. 在项目中安装打包OpenSDK
+
+```bash
+npm install qingtui-h5package-sdk --save-dev
+```
+
+
+2. 在项目根目录下创建离线包资源配置文件 localresource.json
+
+```js
+// localresource.json
+{
+  "version": "版本号" // 可选，默认读取当前目录下package.json version 字段
+}
+```
+
+3. 在 localresource.json 中添加 assets 配置，声明项目中静态资源（编译产物、静态资源皆可）与线上资源的映射关系。
+示例：
+
+```js
+{
+  // key为应用的URL路径地址，值为本地文件或目录
+  "assets: {
+    // 目录
+    "https://www.example.com/myapp": "./dist"
+  },
+}
+```
+
+4. 在 localresource.json 中添加 externalAssets 配置，声明应用中依赖的外部资源（如 react、 react-dom等）。
+
+```js
+{
+  "externalAssets": [
+    "https://unpkg.com/react@16.7.0/umd/react.production.min.js"
+  ]
+}
+```
+
+
+## 命令列表
+
+### pack
+本地离线包资源打包，在本地输出打包后的离线资源文件，文件格式为.zip。离线包ID自动在 localresource.json 文件中查找。
+用法：
+
+```bash
+npx h5package pack
+```
+
+
+## 打包配置文件 Config
+
+```js
+{
+  // 默认读取当前目录下package.version
+  version: string;
+  // 线上资源URL和本地文件、目录映射关系。key 为线上资源URL地址，值 为本地文件地址。支持 文件 和 目录
+  // 示例：
+  // {
+  //   assets: {
+  //     键值为目录。将 ./dist 目录下的资源添加到 https://www.example.com/myapp 下
+  //     "https://www.example.com/myapp": "./dist",
+  //     键值为文件。将  ./favorite.icon 添加到  https://www.example.com/myapp/favorite.ico
+  //     "https://www.example.com/myapp/favorite.ico": "./favorite.ico",
+  //   }
+  // }
+  assets: Record<string, string>;
+  // 依赖的外部URL列表。
+  // 应用中往往会依赖一些外部资源，如react、vue等外部公共库CDN资源。
+  // 添加到此配置后，打包脚本会自动通过HTTP GET请求从网络下载资源内容进行打包。
+  // 示例：
+  // {
+  //   "externalAssets": [
+  //     "https://unpkg.com/react@16.7.0/umd/react.production.min.js",
+  //     "https://unpkg.com/vue@3.2.45/dist/vue.global.js",
+  //     "https://unpkg.com/jquery@3.6.1/dist/jquery.js"
+  //   ]
+  // }
+  externalAssets: string[];
+}
+```
+

package/dist/PackagePacker.d.ts

@@ -0,0 +1,23 @@
+import archiver from 'archiver';
+export declare const MAX_PATH_LENGTH = 88;
+export declare function urlToPath(url: string): string;
+export declare class PackagePacker {
+    readonly options: {
+        filename: string;
+    };
+    arch: archiver.Archiver;
+    file: string;
+    includeUrlSet: Set<string>;
+    private prom;
+    private output;
+    private bizData;
+    constructor(options: {
+        filename: string;
+    });
+    appendFile(url: string, fileOrDirectory: string): Promise<void>;
+    private _file;
+    appendDirectory(url: string, directory: string): Promise<void>;
+    appendUrl(url: string): Promise<void>;
+    appendBizData(bizData: Record<string, unknown>): Promise<void>;
+    finalize(): Promise<string>;
+}

package/dist/PackagePacker.js

@@ -0,0 +1,95 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PackagePacker = exports.urlToPath = exports.MAX_PATH_LENGTH = void 0;
+const archiver_1 = __importDefault(require("archiver"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const download_1 = __importDefault(require("download"));
+const glob_1 = __importDefault(require("glob"));
+// 文件路径最大长度是100，扣除"web_assets/"目录，实际最大长度是89;
+exports.MAX_PATH_LENGTH = 88;
+function urlToPath(url) {
+    let uri;
+    try {
+        uri = new URL(url);
+    }
+    catch (error) {
+        throw new Error(`无效的资源地址: ${url}`);
+    }
+    if (uri.protocol !== 'https:') {
+        throw new Error(`无效的资源地址: ${url}, 离线包只支持 https 协议`);
+    }
+    const host = uri.port ? `${uri.hostname}@${uri.port}` : uri.hostname;
+    let p = `${host}${uri.pathname}`;
+    if (p.endsWith('/')) {
+        p = p.slice(0, -1);
+    }
+    return p;
+}
+exports.urlToPath = urlToPath;
+class PackagePacker {
+    constructor(options) {
+        this.options = options;
+        this.includeUrlSet = new Set();
+        this.bizData = {};
+        this.file = path_1.default.join(process.cwd(), options.filename);
+        this.output = fs_extra_1.default.createWriteStream(this.file);
+        this.arch = (0, archiver_1.default)('zip', { zlib: { level: 9 } });
+        this.prom = new Promise((r, c) => {
+            this.arch.on('error', (err) => {
+                console.error('打包失败', err);
+                c(err);
+            });
+            this.output.on('close', () => {
+                r();
+            });
+        });
+        this.arch.pipe(this.output);
+    }
+    async appendFile(url, fileOrDirectory) {
+        const p = path_1.default.resolve(fileOrDirectory);
+        const stat = await fs_extra_1.default.stat(p);
+        if (stat.isDirectory()) {
+            await this.appendDirectory(url, p);
+        }
+        else if (stat.isFile()) {
+            this._file(url, p);
+        }
+        else {
+            throw new Error(`无效的文件或目录: ${p}`);
+        }
+    }
+    _file(url, filename) {
+        const fullFilePath = urlToPath(url);
+        if (fullFilePath.length > exports.MAX_PATH_LENGTH) {
+            console.warn(`以下文件被忽略(文件路径长度>${exports.MAX_PATH_LENGTH}): ${path_1.default.relative(process.cwd(), filename)}`);
+            return;
+        }
+        this.arch.file(filename, { name: fullFilePath });
+        this.includeUrlSet.add(url);
+    }
+    async appendDirectory(url, directory) {
+        const prefixURL = new URL(url);
+        const files = glob_1.default.sync('**/*', { cwd: directory, nodir: true });
+        for (const file of files) {
+            const filename = path_1.default.join(directory, file);
+            const fullUrl = new URL(path_1.default.join(prefixURL.pathname, file), prefixURL.origin).toString();
+            this._file(fullUrl, filename);
+        }
+    }
+    async appendUrl(url) {
+        const content = await (0, download_1.default)(url);
+        this.arch.append(content, { name: urlToPath(url) });
+    }
+    async appendBizData(bizData) {
+        this.bizData = bizData;
+    }
+    async finalize() {
+        await this.arch.finalize();
+        return Promise.resolve(this.prom).then(() => this.file);
+    }
+}
+exports.PackagePacker = PackagePacker;

package/dist/cli/h5package.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/h5package.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const md5_file_1 = __importDefault(require("md5-file"));
+const PackagePacker_1 = require("../PackagePacker");
+function verifyVersion(version) {
+    const REGEXP = /^(\d{1,2})\.(\d{1,2})\.(\d{1,2})$/;
+    if (!REGEXP.test(version)) {
+        throw new Error('版本号格式不正确');
+    }
+}
+async function readPackageVersion() {
+    if (!fs_extra_1.default.existsSync('./package.json')) {
+        throw new Error('package.json is missing');
+    }
+    const config = await fs_extra_1.default.readJson('./package.json');
+    verifyVersion(config.version);
+    return config.version;
+}
+async function readResourceConfig(opts) {
+    if (!fs_extra_1.default.existsSync(opts.config)) {
+        throw new Error(`配置文件不存在: ${opts.config}`);
+    }
+    const config = await fs_extra_1.default.readJson(opts.config, {
+        throws: true,
+    });
+    if (!config.version) {
+        config.version = await readPackageVersion();
+    }
+    return config;
+}
+async function pack(opts) {
+    const { version, assets = {}, externalAssets = [] } = opts.config;
+    const assetKeys = Object.keys(assets);
+    const CACHE_DIR = path_1.default.join('node_modules', '.cache', 'h5packer');
+    const TEMP_ZIP_NAME = 'temp.zip';
+    const TEMP_ZIP_REL = path_1.default.join(CACHE_DIR, TEMP_ZIP_NAME);
+    await fs_extra_1.default.ensureDir(CACHE_DIR);
+    // ======================================================
+    // 第一轮打包 → node_modules/.cache/h5packer/temp.zip
+    // ======================================================
+    const firstPacker = new PackagePacker_1.PackagePacker({
+        filename: TEMP_ZIP_REL,
+    });
+    for (const assetKey of assetKeys) {
+        await firstPacker.appendFile(assetKey, assets[assetKey]);
+    }
+    for (const externalAsset of externalAssets) {
+        await firstPacker.appendUrl(externalAsset);
+    }
+    await firstPacker.finalize();
+    // -------- 计算 md5 --------
+    const firstZipBuffer = await fs_extra_1.default.readFile(TEMP_ZIP_REL);
+    const md5 = md5_file_1.default.sync(TEMP_ZIP_REL);
+    // ======================================================
+    // 第二轮打包 → 最终包
+    // ======================================================
+    const finalPacker = new PackagePacker_1.PackagePacker({
+        filename: opts.filename,
+    });
+    finalPacker.arch.append(firstZipBuffer, { name: 'app.zip' });
+    finalPacker.arch.append(JSON.stringify({
+        includeUrls: Array.from(firstPacker.includeUrlSet),
+        bizData: {
+            version,
+            md5,
+        },
+    }), { name: 'manifest.json' });
+    await finalPacker.finalize();
+    try {
+        fs_extra_1.default.removeSync(CACHE_DIR);
+    }
+    finally {
+        console.log('离线包已生成:', finalPacker.file);
+    }
+}
+commander_1.program
+    .summary('轻推H5离线包SDK')
+    .version('1.0.0', '-v, --version', 'output the current version')
+    .addHelpCommand('help', 'display help for command');
+commander_1.program
+    .command('pack')
+    .description('打包生成离线包')
+    .option('--config <config>', '打包配置', './localresource.json')
+    .action(async function (opts) {
+    const config = await readResourceConfig(opts);
+    await pack({
+        filename: `h5package.zip`,
+        config,
+    });
+});
+commander_1.program.parseAsync(process.argv);

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './PackagePacker';

package/dist/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./PackagePacker"), exports);

package/dist/types.d.ts

@@ -0,0 +1,5 @@
+export interface PackerConfig {
+    version?: string;
+    assets: Record<string, string>;
+    externalAssets?: string[];
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "qingtui-h5package-sdk",
+  "version": "0.0.1",
+  "description": "轻推H5离线包工具",
+  "main": "dist/index.js",
+  "directories": {
+    "dist": "dist"
+  },
+  "bin": {
+    "h5package": "./dist/cli/h5package.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "start": "tsc --watch",
+    "build": "rm -rf ./dist && tsc",
+    "lint": "eslint --ext .ts",
+    "lint:fix": "eslint  --fix --ext .ts",
+    "commit": "git cz",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "qingtui"
+  ],
+  "author": "paseo",
+  "license": "MIT",
+  "devDependencies": {
+    "@changesets/cli": "^2.26.0",
+    "@tsconfig/node12": "^1.0.11",
+    "@tsconfig/node14": "^1.0.3",
+    "@types/ali-oss": "^6.16.6",
+    "@types/archiver": "^5.3.1",
+    "@types/download": "^8.0.1",
+    "@types/fs-extra": "^9.0.13",
+    "@types/jest": "^29.2.3",
+    "@types/node": "^18.11.9",
+    "@types/uuid": "^8.3.4",
+    "@typescript-eslint/eslint-plugin": "^5.44.0",
+    "@typescript-eslint/parser": "^5.44.0",
+    "cz-conventional-changelog": "^3.3.0",
+    "decompress": "^4.2.1",
+    "eslint": "^8.28.0",
+    "jest": "^29.3.1",
+    "ts-jest": "^29.0.3",
+    "typescript": "^4.9.3"
+  },
+  "dependencies": {
+    "archiver": "^5.3.1",
+    "commander": "^9.4.1",
+    "download": "^8.0.0",
+    "fs-extra": "^10.1.0",
+    "glob": "^8.0.3",
+    "uri-js": "^4.4.1",
+    "uuid": "^9.0.0"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  }
+}