Unlighthouse项目中解决localStorage访问权限问题的技术分析

在使用Unlighthouse进行网站性能监测时，遇到需要认证的页面是常见场景。本文针对一个典型的技术问题——"Failed to read the 'localStorage' property from 'Window': Access is denied for this document"错误进行深入分析，并提供解决方案。

问题背景

当开发者尝试使用Unlighthouse对需要认证的网站进行性能分析时，通常会配置authenticate()钩子函数来完成登录流程。一个典型的实现方式包括：

1. 通过API调用获取access_token和refresh_token
2. 使用page.setCookie()方法设置这些认证token
3. 期望通过这些cookie访问受保护的页面

然而，在执行setCookie操作时，系统可能会抛出DOMException，提示无法访问localStorage属性。

根本原因分析

这个问题的核心在于浏览器安全机制。当页面尚未加载任何内容时，浏览器上下文并未完全建立，此时尝试操作cookie或localStorage会触发安全限制。具体表现为：

1. Puppeteer页面对象在没有加载任何URL前，没有完整的浏览器上下文
2. 直接操作cookie或storage API会因安全限制而失败
3. 错误信息表面上是localStorage访问被拒，但根源在于上下文缺失

解决方案

根据项目维护者的建议，正确的处理方式应该是：

1. 首先导航到目标网站的一个页面（通常是登录页）
2. 等待页面上下文完全建立
3. 然后再执行认证和cookie设置操作

修正后的代码结构应该是：

export default {
  hooks: {
    async authenticate(page) {
      // 首先导航到目标页面
      await page.goto('http://localhost:3000/login');
      
      // 然后执行认证流程
      const tokens = await fetch('...', {
        method: 'POST',
        body: JSON.stringify({ ... }),
      }).then(r => r.json());
      
      // 设置cookie
      await page.setCookie({
        name: 'access-token',
        value: tokens.access_token,
        domain: 'localhost',
        path: '/',
      });
      // 其他cookie设置...
    }
  }
}

技术要点

1. 上下文初始化：浏览器页面对象需要加载实际内容后才能建立完整的安全上下文
2. 执行顺序：认证流程必须在页面导航完成后进行
3. 错误处理：建议在代码中添加适当的错误处理逻辑，特别是对于网络请求和页面导航操作

最佳实践建议

1. 对于需要认证的网站分析，建议先导航到登录页面
2. 考虑添加等待逻辑，确保页面完全加载后再执行后续操作
3. 对于复杂的认证流程，可以分步调试，先确保基本导航和cookie设置工作正常
4. 使用headless: false模式进行调试时，可以直观观察页面加载和操作过程

通过遵循这些原则，可以避免常见的权限相关问题，确保Unlighthouse能够顺利完成对认证页面的性能分析工作。