Cypress测试文件无法调用自定义命令saveSessionStorage、restoreSessionStorage报错怎么办

云上老周

2026-9-27

报错原因

这个ts(2339)错误是TypeScript类型检查导致的，和代码运行逻辑无关，常见诱因有3个：

你没有给自定义的Cypress命令补充TS类型声明，TS不知道cy对象上新增了两个方法，因此抛出类型不存在的错误
导入路径大小写错误：你提到的cypress/Support/Index.js不符合Cypress的默认路径规范，Cypress默认读取的是全小写的cypress/support/目录下的文件，类Unix系统对路径大小写敏感，会导致commands.js没有被正确加载
你自定义命令中用到的LOCAL_STORAGE_MEMORY变量没有预先声明，也可能触发类型报错

解决方案

步骤1：添加自定义命令类型声明

在cypress/support目录下新建index.d.ts类型声明文件，写入以下内容：

/// <reference types="cypress" />

declare namespace Cypress {
  interface Chainable {
    saveSessionStorage(): Cypress.Chainable<void>
    restoreSessionStorage(): Cypress.Chainable<void>
  }
}

declare global {
  var LOCAL_STORAGE_MEMORY: Record<string, string>
}

export {}

步骤2：配置TS识别类型文件

打开项目根目录的tsconfig.json，在include数组中添加类型文件路径，确保TS能读取到声明：

{
  "compilerOptions": {
    // 保留你原有的配置，新增下面一行即可
    "types": ["cypress"]
  },
  "include": [
    "cypress/**/*",
    "cypress/support/index.d.ts"
  ]
}

步骤3：修正支持文件导入路径

如果你用的是Cypress 10及以上版本，打开cypress/support/e2e.js，添加import './commands'即可，不需要新建大写开头的Index.js
如果你用的是Cypress 9及以下版本，确认cypress/support/index.js（全小写）中已经导入了commands.js

步骤4：补全全局变量声明

在cypress/support/commands.js顶部添加变量初始化代码，避免运行时报错：

// 顶部新增
const LOCAL_STORAGE_MEMORY = {};

// 保留你原有的自定义命令代码
Cypress.Commands.add('saveSessionStorage', () => {
  Object.keys(localStorage).forEach(key => {
    LOCAL_STORAGE_MEMORY[key] = localStorage[key];
  });
});

Cypress.Commands.add('restoreSessionStorage', () => {
  Object.keys(LOCAL_STORAGE_MEMORY).forEach(key => {
    localStorage.setItem(key, LOCAL_STORAGE_MEMORY[key]);
  });
});

修改完成后重启IDE或者TypeScript服务，报错就会消失。

内容的提问来源于stack exchange，提问作者shreyas