跟随Cypress官方教程遇‘compiled under --isolatedModules’编译错误求助

问题本质 #

这个错误是TypeScript的isolatedModules编译规则导致的：它要求每个文件要么是带import/export的模块，要么是纯脚本。Cypress的自定义命令文件需要被识别为模块，但直接加export {}会破坏Cypress默认的全局类型注入逻辑，导致其他文件连锁报错。

新手分步解决指南 #

1. 给命令文件加合法的导入语句
   打开cypress/support/commands.ts，在文件开头加一行Cypress相关的导入，比如：

   import 'cypress'
   

   只要有import语句，TypeScript就会把这个文件当成模块，不需要再加export {}。如果你的命令用到了项目自定义类型（比如用户类型），也可以导入对应类型文件，效果一致。

2. 单独声明自定义命令的类型
   不要在命令文件里乱加类型代码，新建一个cypress/support/commands.d.ts文件，专门用来声明自定义命令的类型。比如教程里的login命令可以这么写：

   declare namespace Cypress {
     interface Chainable {
       login(email: string, password: string): Chainable<void>
     }
   }
   

   这个文件不需要任何import/export，TypeScript会自动把它识别为全局类型声明，不会触发隔离模块错误。

3. 检查tsconfig.json配置
   打开项目根目录的tsconfig.json，确认两个关键点：

   • compilerOptions里的isolatedModules设为true（Cypress默认推荐开启）
   • include数组包含cypress/**/*，确保Cypress的所有文件都被TypeScript识别：

     {
       "compilerOptions": {
         "isolatedModules": true,
         // 其他配置保持不变
       },
       "include": [
         "src/**/*",
         "cypress/**/*"
       ]
     }
     

4. 清理多余的export {}
   把之前为了临时解决错误添加的所有export {}语句删掉，这些语句会导致全局类型失效，引发其他文件的报错。

5. 重启相关服务
   关闭当前运行的Cypress测试窗口，再重启你的IDE（比如VS Code），让TypeScript重新加载所有配置和文件。

验证方法 #

重新启动Cypress运行测试，若自定义命令能正常调用，且不再出现compiled under --isolatedModules错误，就说明问题已解决。

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