Windows系统下Cypress路径拼接错误的解决方案咨询

问题背景 #

在Windows系统使用Cypress 12.8.1时触发路径无效字符错误，报错信息如下：

Error: Path contains invalid characters: C:\Users\someUser\AppData\Roaming\Cypress\cy\production\projects\config-703c6b3a413d9453b96ab30fb157dca7\bundles\C:\task\shop\ui\main
at checkPath (C:\task\shop\node_modules@cypress\browserify-preprocessor\node_modules\fs-extra\lib\mkdirs\make-dir.js:20:21)

Mac系统无此问题，已尝试相关公开方案但无效，且node_modules中无对应修复，以下是可行临时解决办法：

方案1：手动patch路径校验逻辑 #

找到node_modules/@cypress/browserify-preprocessor/node_modules/fs-extra/lib/mkdirs/make-dir.js中的checkPath函数，添加Windows重复盘符路径的处理逻辑：

function checkPath (path) {
  // 新增：处理Windows下路径嵌套盘符的情况
  if (process.platform === 'win32') {
    // 移除重复的盘符前缀，保留最后一个合法盘符路径
    const driveRegex = /([A-Za-z]:\\)/g
    const matches = path.match(driveRegex)
    if (matches && matches.length > 1) {
      const lastDriveIndex = path.lastIndexOf(matches[matches.length - 1])
      path = path.slice(lastDriveIndex)
    }
  }

  // 原有校验逻辑...
  if (path.length === 0) {
    throw new Error('Path cannot be empty')
  }
  // ...其余原有代码
}

修改后重启Cypress，该逻辑会自动截断路径中重复的盘符前缀，避免无效路径报错。

方案2：替换为独立版browserify预处理器 #

默认预处理器可能存在路径拼接bug，改用独立包并自定义路径处理：

1. 安装独立预处理器：

npm install cypress-browserify-preprocessor@latest --save-dev

2. 在cypress.config.js中配置并添加路径修正钩子：

const { defineConfig } = require('cypress')
const browserify = require('cypress-browserify-preprocessor')

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      const options = browserify.defaultOptions
      // 自定义文件路径处理，将绝对路径转为相对路径
      options.browserifyOptions.transform.push((file) => {
        if (process.platform === 'win32' && file.path.startsWith('C:\\')) {
          file.path = file.path.replace(config.projectRoot, '.')
        }
        return file
      })
      on('file:preprocessor', browserify(options))
    },
  },
})

方案3：切换到Webpack预处理器 #

绕过browserify的路径问题，改用Webpack预处理器：

1. 安装依赖：

npm install cypress-webpack-preprocessor webpack@5 --save-dev

2. 在cypress.config.js中配置：

const { defineConfig } = require('cypress')
const webpackPreprocessor = require('cypress-webpack-preprocessor')

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      on('file:preprocessor', webpackPreprocessor())
    },
  },
})

方案4：使用短路径或映射盘符 #

• 将项目移至无特殊字符的短路径下，比如C:\task\shop_ui，避免Cypress拼接路径时出现嵌套盘符。
• 用Windowssubst命令映射项目目录到新盘符：

subst Z: C:\task\shop\ui

之后切换到Z盘路径运行Cypress，避免路径嵌套问题。

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