> ## Documentation Index
> Fetch the complete documentation index at: https://help.dingtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 钉钉H5应用离线包

> 本文档介绍什么是离线包管理和离线包的使用流程。

## 什么是离线包

离线包是将包括 HTML、JavaScript、CSS 等页面内静态资源打包到一个压缩包内。用户使用应用时，客户端将离线包下载到本地，然后通过钉钉客户端打开，直接从本地加载离线包，从而最大程度地摆脱网络环境对钉钉H5微应用的影响。

## 接入限制

* 仅适用移动端，且客户端版本≥6.5.20。
* 上传的离线资源总体积不超过10M。

## 接入步骤

### 步骤一：开启微应用离线包功能

1. 登录[钉钉开发者后台](https://open-dev.dingtalk.com/)。
2. 选择需开启离线包的应用。
3. 在导航栏单击 **版本管理与发布**。在 **版本管理与发布** 页面，点击 **离线包管理** 按钮后，再单击 **确定**。![iShot2022-07-28 14](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/0729898561/p472378.png)

### 步骤二：离线包打包

1. 在项目工程中，通过npm安装 [dingtalk-h5package-opensdk](https://www.npmjs.com/package/dingtalk-h5package-opensdk)。

   ```
   npm install dingtalk-h5package-opensdk --save-dev
   ```
2. 在项目工程中，创建离线包打包配置文件 `localresource.json`。文件示例如下：

   ```
   {
     "miniAppId": "打包的离线包ID",
     // 线上资源URL和本地文件、目录映射关系。key 为本地资源对应的线上资源URL路径，值 为本地资源目录。
     "assets": {
       // 键值为目录。此配置意思是将 ./dist 目录下的资源添加到 https://www.example.com/myapp 路径下
       "https://www.example.com/myapp": "./dist"
     },
     // 依赖的外部URL列表。
     "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"
     ]
   }
   ```
3. 在项目工程下运行打包命令，在本地输出格式为 `${离线包ID}.zip`的资源文件 。

   ```
   npx h5package pack
   ```

### 步骤三：上传离线包

在 **版本管理与发布** 页面，单击 **请上传H5资源包（.zip、.tar、.tar.gz）**，选中步骤二的压缩包资源，等待离线包解析完成。![iShot2022-07-28 14](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/0729898561/p472381.png)

### 步骤四：发布离线包

选择目标版本离线包，单击 **发布** 按钮，再单击 **确认发布** 即可。![iShot2022-07-28 14](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/0729898561/p472384.png)

## 使用方式

在业务URL的Query参数中，拼接dd\_mini\_app\_id字段，值从 **离线包管理** 页面中的 **离线包ID** 获取。![iShot2022-07-28 14](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/0729898561/p472386.png)

使用示例：

正常URL：[https://www.example.com/myapp/index.html](https://www.example.com/myapp/index.html)

离线包URL：[https://www.example.com/myapp/index.html?dd\_mini\_app\_id=500000000xxxxx](https://www.example.com/myapp/index.html?dd_mini_app_id=500000000xxxxx)

## 调试工具

钉钉提供了离线包调试工具，其主要功能为：**手机本地离线包信息检查** 和 **H5离线包页面DevTools**。

使用调试工具的客户端版本要求：Android≥6.5.35；iOS≥6.5.35

工具使用方式：请使用钉钉客户端扫描以下二维码。

![调试工具二维码](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/2106160661/p477688.png)

扫描二维码后，进入调试工具首页，页面如下图所示：![iShot2022-08-16 11](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/0281260661/p477792.png)

### H5页面诊断

页面诊断工作机制：打开H5离线包页面时，容器向页面注入DevTools，监听页面的运行情况。

操作步骤：

1. 点击 **H5页面诊断**。
2. 输入开启H5离线包的URL。
3. 点击 **开始诊断**，进入诊断页面。

操作示意图如下：![iShot2022-08-16 11](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/0281260661/p477819.png)

### 本地离线包检查

操作步骤：

1. 点击 **本地离线包查询**。
2. 输入miniAppId，即离线包ID。
3. 点击 **查看离线包信息**。

操作效果示意图如下：![iShot2022-08-16 11](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/0281260661/p477833.png)