Cypress无法识别别名@，解析为Node模块报错求助

数据老陈

2026-8-23

解决Cypress无法解析Next.js路径别名@的问题

问题原因

项目中Next.js通过tsconfig.json配置了@作为路径别名，但Cypress的Webpack编译环境未同步该配置，导致无法解析@/helpers/isServer这类路径，触发编译错误。

解决方案

方法1：手动添加Webpack别名配置

修改Cypress插件文件（cypress/plugins/index.js），手动为Webpack添加别名解析规则：

/// <reference types="cypress" />
const injectDevServer = require('@cypress/react/plugins/next');
const path = require('path');

module.exports = (on, config) => {
  injectDevServer(on, config);

  // 配置Webpack解析@别名，指向项目src目录
  on('webpack:config', (webpackConfig) => {
    webpackConfig.resolve.alias = {
      ...webpackConfig.resolve.alias,
      '@': path.resolve(process.cwd(), 'src')
    };
    return webpackConfig;
  });

  return config;
};

方法2：自动同步tsconfig路径配置（推荐）

若项目中别名规则较多，用插件自动同步tsconfig.json的配置更高效：

安装依赖：

npm install tsconfig-paths-webpack-plugin --save-dev

修改Cypress插件文件：

/// <reference types="cypress" />
const injectDevServer = require('@cypress/react/plugins/next');
const TsconfigPathsPlugin = require('tsconfig-paths-webpack-plugin');
const path = require('path');

module.exports = (on, config) => {
  injectDevServer(on, config);

  // 加载tsconfig里的路径别名配置
  on('webpack:config', (webpackConfig) => {
    webpackConfig.resolve.plugins = [
      ...(webpackConfig.resolve.plugins || []),
      new TsconfigPathsPlugin({
        configFile: path.resolve(process.cwd(), 'tsconfig.json')
      })
    ];
    return webpackConfig;
  });

  return config;
};

额外配置：让Cypress的TypeScript识别别名

如果测试文件中也用到@别名，需在cypress/tsconfig.json同步配置：

{
  "extends": "../tsconfig.json",
  "compilerOptions": {
    "baseUrl": "../",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": ["**/*.ts", "**/*.tsx"]
}