cordova-plugin-whitelist

Cordova 官方核心插件，用于控制应用对外部资源的访问权限，包括网络请求、外部应用跳转和 WebView 导航。它通过白名单机制有效防范跨站请求伪造（CSRF）、恶意 URL 跳转等安全风险，是保障 Cordova 应用安全性的关键组件。

重要提示： 该插件在Cordova10.0开始，已在Android和iOS中废弃，插件已失效，因此该插件也在OHOS系统中功能失效，但保留插件接口，主要兼容老版本的Android或iOS项目移植使用，如果您是新项目，无需安装该插件。

安装指南

1. 基础安装（推荐）

# 安装hcordova
npm install -g hcordova

# 全平台安装
hcordova plugin add cordova-plugin-whitelist

2. 安装指定版本

如需兼容特定 Cordova 版本，可指定插件版本号：

# 安装 1.0.0 稳定版

hcordova plugin add cordova-plugin-whitelist@1.0.0 --platform ohos

3. 开发版安装

如需测试最新功能，可从 GitCode 仓库安装开发分支：

hcordova plugin add https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-whitelist.git --platform ohos

4. 卸载插件

#全平台卸载
hcordova plugin remove cordova-plugin-whitelist

#指定OHOS卸载
hcordova plugin remove cordova-plugin-whitelist --platform ohos

核心功能说明

插件通过三类白名单规则实现精细化权限控制，所有配置均在项目根目录的 config.xml 中完成

白名单类型	控制范围	配置标签	适用平台
网络请求白名单	控制应用发起的 XMLHttpRequest、WebSocket、图片 / 脚本 / 字体等资源加载请求	<access>	所有支持平台
导航白名单	控制应用内 WebView 可直接导航到的外部 URL（不跳转外部浏览器）	<allow-navigation>	所有支持平台

详细配置指南

1. 网络请求白名单（<access> 标签）

控制应用所有网络资源加载，支持通配符、协议限制和子域名匹配。

基础语法

<!-- 推荐配置 -->
<access origin="*" />

<!-- 允许访问指定域名 -->
<access origin="https://api.example.com" />

<!-- 允许访问指定域名及其所有子域名 -->
<access origin="https://*.example.com" />

<!-- 允许访问所有 HTTPS/WSS 安全域名（推荐） -->
<access origin="https://*" />

<!-- 允许访问指定端口（需完整指定协议+域名+端口） -->
<access origin="https://api.example.com:8443" />

2. 导航白名单（<allow-navigation> 标签）

控制 WebView 可直接导航的 URL，未配置的 URL 会触发系统浏览器打开（或被拦截）。

常用配置

<!-- 推荐配置 -->
<allow-navigation href="*" />

<!-- 允许导航到应用主域名下所有路径 -->
<allow-navigation href="https://app.example.com/*" />

<!-- 允许导航到子域名 -->
<allow-navigation href="https://*.app.example.com" />

许可证

本插件基于 Apache License 2.0 开源，详见 LICENSE 文件。

资源参考

1. OHOS：https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-whitelist

2. Android、ios插件说明：https://www.npmjs.com/package/cordova-plugin-whitelist