Android network_security_config.xml 安卓网络安全配置文件怎么写

Android的network_security_config.xml是系统提供的用于自定义应用网络安全行为的配置文件，开发者可以通过该文件灵活控制应用是否允许明文流量、信任哪些证书、不同域名采用不同的安全策略等，无需修改Java或Kotlin代码即可调整网络安全规则。

配置文件的基本结构

network_security_config.xml需要放在Android项目的res/xml目录下，根标签为network-security-config，内部可以包含base-config、domain-config、debug-overrides等子标签，分别对应基础配置、域名专属配置、调试模式覆盖配置。

基础配置示例代码如下：

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <!-- 基础配置，对所有域名生效 -->
    <base-config>
        <trust-anchors>
            <!-- 信任系统预装证书 -->
            <certificates src="system" />
        </trust-anchors>
    </base-config>
</network-security-config>

常用配置场景

允许明文流量（HTTP请求）

Android 9及以上版本默认禁止明文流量，如果应用需要访问HTTP接口，可以通过配置文件开启明文流量允许，示例代码如下：

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config>
        <!-- 允许所有域名的明文流量 -->
        <trust-anchors>
            <certificates src="system" />
        </trust-anchors>
        <!-- cleartextTrafficPermitted 设置为true表示允许明文 -->
        <cleartextTrafficPermitted>true</cleartextTrafficPermitted>
    </base-config>
</network-security-config>

如果只需要对特定域名允许明文流量，可以使用domain-config标签，示例代码如下：

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config>
        <!-- 仅对ippipp.com域名生效 -->
        <domain includeSubdomains="true">ippipp.com</domain>
        <trust-anchors>
            <certificates src="system" />
        </trust-anchors>
        <cleartextTrafficPermitted>true</cleartextTrafficPermitted>
    </domain-config>
</network-security-config>

配置自定义可信证书

如果应用需要信任自签名的证书或者私有CA颁发的证书，可以将证书文件放在res/raw目录下，然后在配置文件中引用，示例代码如下：

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config>
        <trust-anchors>
            <!-- 信任系统证书 -->
            <certificates src="system" />
            <!-- 信任raw目录下的自定义证书，文件名为my_cert.pem -->
            <certificates src="@raw/my_cert" />
        </trust-anchors>
    </base-config>
</network-security-config>

调试模式专属配置

开发阶段可能需要信任Charles、Fiddler等抓包工具的证书，但是正式包不需要，这时候可以使用debug-overrides标签，该配置仅在debug构建类型下生效，示例代码如下：

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config>
        <trust-anchors>
            <certificates src="system" />
        </trust-anchors>
    </base-config>
    <!-- 调试模式下的覆盖配置 -->
    <debug-overrides>
        <trust-anchors>
            <!-- 信任用户安装的证书，抓包工具证书通常安装为用户证书 -->
            <certificates src="user" />
        </trust-anchors>
    </debug-overrides>
</network-security-config>

在AndroidManifest中引用配置

编写完network_security_config.xml后，需要在AndroidManifest.xml的application标签中添加android:networkSecurityConfig属性引用该文件，示例代码如下：

<application
    android:name=".MyApplication"
    android:icon="@mipmap/ic_launcher"
    android:label="@string/app_name"
    android:networkSecurityConfig="@xml/network_security_config"
    android:theme="@style/Theme.MyApp">
    <!-- 其他组件声明 -->
</application>

注意事项

• 配置文件的文件名可以自定义，只要放在res/xml目录下，并且在Manifest中正确引用即可。
• domain标签的includeSubdomains属性设置为true时，会匹配该域名的所有子域名。
• 如果同时配置了base-config和domain-config，域名专属配置会优先生效。
• 正式上线前需要检查是否开启了不必要的明文流量允许，避免带来安全风险。

network_security_configAndroid网络安全配置明文流量修改时间：2026-06-12 14:30:18