Ubuntu Server 20.04下Jenkins运行Cypress+Chromium时下载文件无法读取问题求助

我之前也碰到过类似的场景，结合你的描述，问题核心集中在工作目录不一致、无头浏览器下载配置缺失和权限限制这几个点上，下面给你具体的解决步骤：

1. 改用绝对路径配置downloadsFolder #

你当前在cypress.json里配置的是相对路径xmlfiles，但Jenkins运行时的工作目录未必是你的项目根目录（比如Jenkins可能把代码拉到/var/lib/jenkins/workspace/your-project下），这就导致Cypress找不到预期的目录。

如果你的Cypress版本是10+，建议换成cypress.config.js（比静态的cypress.json更灵活），通过path.resolve生成绝对路径：

const { defineConfig } = require('cypress')
const path = require('path')

module.exports = defineConfig({
  downloadsFolder: path.resolve(__dirname, 'xmlfiles'), // 基于配置文件所在目录生成绝对路径
  e2e: {
    // 其他项目配置...
  }
})

如果是旧版本Cypress（仍用cypress.json），可以在plugins/index.js里动态覆盖配置：

const path = require('path')

module.exports = (on, config) => {
  // 从plugins目录往上跳一级到项目根目录，拼接xmlfiles路径
  config.downloadsFolder = path.resolve(__dirname, '../xmlfiles')
  return config
}

2. 配置Chromium无头模式的下载偏好 #

Ubuntu Server上运行的是无头Chromium，默认下载行为和桌面版有差异，需要显式指定下载路径，确保和Cypress的downloadsFolder完全一致。

在cypress.config.js的setupNodeEvents里添加浏览器配置：

module.exports = defineConfig({
  downloadsFolder: path.resolve(__dirname, 'xmlfiles'),
  e2e: {
    setupNodeEvents(on, config) {
      on('before:browser:launch', (browser = {}, launchOptions) => {
        // 只针对Chromium浏览器配置
        if (browser.family === 'chromium' && browser.name !== 'electron') {
          launchOptions.preferences.default.download.default_directory = config.downloadsFolder
          launchOptions.preferences.default.download.prompt_for_download = false // 禁用下载提示
          launchOptions.preferences.default.directory_upgrade = true // 允许替换已存在的目录
        }
        return launchOptions
      })
    },
  },
})

旧版本则在plugins/index.js里配置：

module.exports = (on, config) => {
  config.downloadsFolder = path.resolve(__dirname, '../xmlfiles')
  
  on('before:browser:launch', (browser, launchOptions) => {
    if (browser.family === 'chromium') {
      launchOptions.preferences.default.download.default_directory = config.downloadsFolder
      launchOptions.preferences.default.download.prompt_for_download = false
      launchOptions.preferences.default.directory_upgrade = true
    }
    return launchOptions
  })
  
  return config
}

3. 确保Jenkins有目录读写权限 #

Jenkins默认用jenkins用户运行，可能没有权限创建或写入你的xmlfiles目录。可以在Jenkins的构建步骤里先添加命令：

mkdir -p xmlfiles && chown -R jenkins:jenkins xmlfiles

如果是测试环境，也可以用更宽松的权限（不推荐生产环境）：

mkdir -p xmlfiles && chmod 775 xmlfiles

4. 验证实际下载路径 #

在你的测试代码里添加一行打印，确认Cypress使用的下载路径是否正确：

cy.log(`实际下载目录：${Cypress.config('downloadsFolder')}`)

然后查看Jenkins的构建日志，确认路径是你预期的绝对路径，避免出现路径拼接错误。

5. 处理Ubuntu Server无默认Downloads目录的情况 #

Ubuntu Server默认没有用户的Downloads文件夹，而Cypress在未显式指定downloadsFolder时，会尝试使用系统默认的下载目录，这就会导致找不到目录的问题。所以必须显式配置绝对路径的downloadsFolder，彻底避免这个 fallback 行为。

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