React Native WebView 中启用 localStorage 的解决方案

2025-06-01 10:36:30作者：鲍丁臣Ursa

背景介绍

在 React Native 开发中，WebView 组件是连接原生应用和 Web 内容的重要桥梁。react-native-webview 作为社区维护的流行组件，提供了丰富的功能支持。然而，开发者在使用过程中可能会遇到 localStorage 无法正常工作的问题，特别是在加载本地 HTML 内容时。

问题现象

当开发者尝试在 WebView 中使用 localStorage API 存储数据时，可能会遇到存储失败的情况。这通常发生在以下场景：

通过 source.html 属性直接加载 HTML 内容
使用非标准协议（如 file://）加载本地 HTML 文件
在 Android 平台上使用 WebView 时

这是因为 Chrome 浏览器内核的安全策略限制，要求 localStorage 只能在通过标准协议（http/https）加载的页面中使用。

解决方案

针对这个问题，react-native-webview 提供了配置项来绕过这个限制。开发者可以通过设置 domStorageEnabled 属性来启用 localStorage 功能：

<WebView
  source={{ html: '<html>...</html>' }}
  domStorageEnabled={true}
/>

对于 Android 平台，还需要额外设置以下属性：

<WebView
  source={{ html: '<html>...</html>' }}
  domStorageEnabled={true}
  javaScriptEnabled={true}
  originWhitelist={['*']}
/>

实现原理

domStorageEnabled: 这个属性显式地启用了 WebView 的 DOM 存储功能，包括 localStorage 和 sessionStorage
javaScriptEnabled: 必须启用 JavaScript 才能使用 Web 存储 API
originWhitelist: 设置为 ['*'] 允许加载任何来源的内容

注意事项

虽然启用了 localStorage，但存储的数据仍然遵循同源策略
在 iOS 上，WebView 默认使用 WKWebView，其行为可能与 Android 平台有所不同
大量使用 localStorage 可能会影响应用性能，建议合理控制存储数据量

最佳实践

import React from 'react';
import { WebView } from 'react-native-webview';

const MyWebView = () => (
  <WebView
    source={{ html: `
      <html>
        <body>
          <script>
            localStorage.setItem('key', 'value');
            alert(localStorage.getItem('key'));
          </script>
        </body>
      </html>
    `}}
    domStorageEnabled={true}
    javaScriptEnabled={true}
    originWhitelist={['*']}
  />
);

export default MyWebView;