uniapp 开发工具

主题

离线 AppKey 配置 ​

离线 AppKey 允许您在无网络环境下使用 uniapp 开发工具进行本地打包，确保打包过程的稳定性和私密性。

什么是离线 AppKey ​

作用 ​

离线 AppKey 是一个授权密钥，用于：

  • 在离线环境下验证工具授权
  • 解锁本地打包功能
  • 绑定特定设备或项目
  • 控制授权有效期

与在线模式的区别 ​

特性在线模式离线模式
网络要求需要联网验证无需联网
验证方式实时服务器验证本地密钥验证
稳定性依赖网络稳定性不受网络影响
安全性服务器端控制本地密钥控制

推荐

对于需要频繁打包或网络环境不稳定的团队，强烈推荐使用离线 AppKey。

获取离线 AppKey ​

1. 开通 VIP ​

离线 AppKey 功能需要 VIP 权限：

  1. 访问开通 VIP页面
  2. 选择合适的 VIP 套餐
  3. 完成支付流程

2. 申请 AppKey ​

登录后台管理系统：

  1. 访问后台

    登录 https://admin.example.com

  2. 创建 AppKey

    • 进入"离线 AppKey 管理"
    • 点击"创建新密钥"
    • 填写申请信息

  3. 填写申请信息

    必填项：

    • 密钥名称: 便于识别的名称，如"开发环境"、"生产环境"
    • 绑定类型:
      • 设备绑定：绑定到特定设备
      • 项目绑定：绑定到特定项目
      • 通用密钥：不限设备和项目（推荐）
    • 有效期: 30天、90天、180天、365天

    可选项：

    • 设备标识: 绑定到指定设备的唯一标识
    • 项目 AppID: 绑定到指定 uniapp 项目
    • 备注: 额外说明信息

  4. 提交申请

    • 检查信息无误后提交
    • 系统自动生成 AppKey
    • 通常几秒内完成

3. 下载 AppKey ​

生成后：

  1. 在列表中找到刚创建的 AppKey
  2. 点击"下载"按钮
  3. 保存 appkey.txt 文件到安全位置

重要提示

  • AppKey 仅在创建时可下载一次
  • 请妥善保管 AppKey 文件
  • 不要将 AppKey 上传到公开仓库
  • 定期更换 AppKey 以确保安全

配置 AppKey ​

方式一：通过界面配置 ​

  1. 打开配置界面

    在 uniapp 开发工具中：

    • 点击菜单"设置" > "离线 AppKey"
    • 或使用快捷键 Ctrl/Cmd + K

  2. 导入 AppKey

    • 点击"导入 AppKey"按钮
    • 选择下载的 appkey.txt 文件
    • 或直接复制粘贴 AppKey 内容

  3. 验证 AppKey

    • 点击"验证"按钮
    • 系统会检查 AppKey 有效性
    • 显示 AppKey 信息：
      • 密钥名称
      • 有效期
      • 绑定信息
      • 剩余天数

  4. 保存配置

    • 确认信息无误
    • 点击"保存"
    • 重启工具以应用配置

方式二：通过配置文件 ​

对于批量部署或自动化场景：

  1. 找到配置目录

    配置文件位置：

    • Windows: %APPDATA%\uniapp-tools\config\
    • macOS: ~/Library/Application Support/uniapp-tools/config/
    • Linux: ~/.config/uniapp-tools/

  2. 创建配置文件

    创建或编辑 offline-appkey.json：

    json
    {
  "appkey": "YOUR_APPKEY_STRING_HERE",
  "enabled": true,
  "autoVerify": true
}

  3. 重启工具

    配置文件会在工具启动时自动加载。

AppKey 管理 ​

查看 AppKey 信息 ​

在工具中查看当前 AppKey 状态：

  • 当前状态: 激活/未激活/已过期
  • 有效期: 开始和结束日期
  • 剩余天数: 距离过期的天数
  • 绑定信息: 设备或项目绑定情况

更新 AppKey ​

当 AppKey 即将过期或需要更换：

  1. 在后台生成新的 AppKey
  2. 在工具中导入新 AppKey
  3. 旧 AppKey 自动失效

提示

建议在过期前 7 天更新 AppKey，避免影响打包工作。

删除 AppKey ​

如果不再需要离线模式：

  1. 打开"离线 AppKey"设置
  2. 点击"删除 AppKey"
  3. 确认删除
  4. 工具将恢复到在线验证模式

AppKey 类型详解 ​

1. 设备绑定型 ​

特点：

  • 绑定到特定设备的硬件标识
  • 只能在绑定设备上使用
  • 安全性最高

适用场景：

  • 个人开发者
  • 固定工作站
  • 对安全要求高的项目

获取设备标识：

在工具中：

  • 进入"设置" > "关于"
  • 复制"设备标识"
  • 在申请 AppKey 时填入

2. 项目绑定型 ​

特点：

  • 绑定到特定 uniapp 项目的 AppID
  • 只能为该项目打包
  • 可在不同设备上使用

适用场景：

  • 团队协作开发
  • 需要多设备切换
  • 单一项目的持续集成

项目 AppID：

在 manifest.json 中找到：

json
{
  "appid": "__UNI__1234567"
}

3. 通用密钥 ​

特点：

  • 不限设备和项目
  • 最灵活的使用方式
  • 适合各种场景

适用场景：

  • 多项目开发
  • 频繁切换设备
  • 测试和实验

注意

通用密钥需要妥善保管，避免泄露给未授权人员。

高级配置 ​

环境变量配置 ​

通过环境变量设置 AppKey（适合 CI/CD）：

设置环境变量：

bash
# Linux/macOS
export UNIAPP_TOOLS_APPKEY="your_appkey_here"

# Windows (CMD)
set UNIAPP_TOOLS_APPKEY=your_appkey_here

# Windows (PowerShell)
$env:UNIAPP_TOOLS_APPKEY="your_appkey_here"

在代码中使用：

工具会自动读取环境变量中的 AppKey。

命令行配置 ​

使用命令行参数指定 AppKey：

bash
uniapp-tools build --appkey "your_appkey_here"

配置优先级 ​

当同时存在多种配置方式时，优先级为：

  1. 命令行参数
  2. 环境变量
  3. 配置文件
  4. 界面配置

常见问题 ​

AppKey 验证失败 ​

问题: 提示 AppKey 无效或已过期

解决方案:

  1. 检查 AppKey 是否正确复制（无多余空格）
  2. 确认 AppKey 未过期
  3. 验证设备/项目绑定是否匹配
  4. 检查系统时间是否正确

设备标识不匹配 ​

问题: 提示设备标识不匹配

解决方案:

  1. 确认在正确的设备上使用
  2. 重新获取设备标识
  3. 或申请通用密钥

AppKey 无法导入 ​

问题: 导入 AppKey 时失败

解决方案:

  1. 确认文件格式正确（纯文本）
  2. 检查文件编码（UTF-8）
  3. 尝试复制粘贴方式导入
  4. 检查文件是否损坏

多台设备共用 ​

问题: 需要在多台设备上使用

解决方案:

  1. 申请通用密钥
  2. 或为每台设备申请独立 AppKey
  3. 使用项目绑定型 AppKey

安全建议 ​

保护 AppKey ​

  1. 不要公开分享

    • 不要将 AppKey 提交到版本控制系统
    • 使用 .gitignore 排除配置文件
    gitignore
    # .gitignore
offline-appkey.json
appkey.txt

  2. 使用环境变量

    • 在 CI/CD 中使用加密的环境变量
    • 不要在日志中输出 AppKey

  3. 定期更换

    • 建议每 3-6 个月更换一次
    • 发现泄露时立即更换

  4. 权限控制

    • 限制配置文件的读写权限
    • 只授权必要人员访问

泄露应对 ​

如果 AppKey 泄露：

  1. 立即停用

    • 登录后台管理
    • 停用或删除泄露的 AppKey

  2. 生成新密钥

    • 创建新的 AppKey
    • 更新到所有授权设备

  3. 审查使用记录

    • 检查 AppKey 使用日志
    • 确认是否有异常使用

AppKey 配置清单 ​

配置前确认：

  • [ ] 已开通 VIP 权限
  • [ ] 已生成 AppKey
  • [ ] 已下载并保存 AppKey 文件
  • [ ] 已导入到工具中
  • [ ] 验证通过
  • [ ] 配置文件已备份（可选）
  • [ ] 团队成员已告知（团队项目）

下一步 ​

完成 AppKey 配置后，您可以：

Released under the MIT License.

Copyright © 2026 码农朱哲