如何用NodeJS下载Gmail中的Excel附件？是否仅依赖OAuth2？

可用的库 #

• node-imap/imap-simple：基于IMAP协议的第三方工具，imap-simple是node-imap的封装版，API更简洁，适合直接操作邮件内容与附件。
• googleapis：Google官方提供的API客户端库，直接调用Gmail API，适配官方认证规范，功能更全面稳定。

关于OAuth2认证的说明 #

是的，目前Gmail的IMAP/SMTP服务已逐步淘汰普通密码登录方式——尤其是开启两步验证（2FA）的账号，必须使用OAuth2认证；未开启2FA的账号虽可用应用专用密码，但属于遗留方式，不推荐长期依赖。所以代码中使用OAuth2是当前标准做法。

实现思路与代码示例 #

方式一：使用imap-simple（IMAP协议） #

核心步骤：

1. 在Google Cloud平台创建OAuth2凭据（客户端ID、密钥），获取刷新令牌（refresh token）。
2. 连接Gmail的IMAP服务器（imap.gmail.com，端口993，SSL加密）。
3. 搜索符合条件的邮件（如包含Excel附件、指定发件人/主题）。
4. 解析邮件结构，定位.xlsx/.xls格式的附件。
5. 将附件内容写入本地指定文件夹。

示例代码片段：

const imaps = require('imap-simple');
const fs = require('fs');
const path = require('path');
const { google } = require('googleapis');

// OAuth2配置
const oauth2Client = new google.auth.OAuth2(
  'YOUR_CLIENT_ID',
  'YOUR_CLIENT_SECRET',
  'YOUR_REDIRECT_URI'
);
oauth2Client.setCredentials({ refresh_token: 'YOUR_REFRESH_TOKEN' });

const config = {
  imap: {
    user: 'your-email@gmail.com',
    xoauth2: async () => {
      const { token } = await oauth2Client.getAccessToken();
      return token;
    },
    host: 'imap.gmail.com',
    port: 993,
    tls: true,
    authTimeout: 3000
  }
};

async function downloadExcelAttachments() {
  const connection = await imaps.connect(config);
  await connection.openBox('INBOX');

  // 搜索条件：未读邮件 + 包含Excel附件
  const searchCriteria = ['UNSEEN', ['HEADER', 'Content-Type', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet']];
  const fetchOptions = {
    bodies: ['HEADER', 'TEXT'],
    struct: true
  };

  const messages = await connection.search(searchCriteria, fetchOptions);
  for (const msg of messages) {
    const parts = imaps.getParts(msg.attributes.struct);
    // 筛选Excel附件
    const excelParts = parts.filter(part => {
      return part.disposition && part.disposition.type === 'ATTACHMENT' && 
             (part.params.name.endsWith('.xlsx') || part.params.name.endsWith('.xls'));
    });

    for (const part of excelParts) {
      const attachment = await connection.getPartData(msg, part);
      const savePath = path.join('你的本地文件夹路径', part.params.name);
      fs.writeFileSync(savePath, attachment, 'base64');
      console.log(`已保存附件：${savePath}`);
    }
  }
  await connection.end();
}

downloadExcelAttachments().catch(err => console.error(err));

方式二：使用Google官方Gmail API #

核心步骤：

1. 在Google Cloud平台启用Gmail API，创建OAuth2凭据。
2. 通过OAuth2授权获取访问令牌（access token）。
3. 调用users.messages.list接口筛选带Excel附件的邮件。
4. 调用users.messages.get获取邮件详情，定位附件ID。
5. 调用users.messages.attachments.get获取附件内容，解码后保存到本地。

示例代码片段：

const { google } = require('googleapis');
const fs = require('fs');
const path = require('path');

const oauth2Client = new google.auth.OAuth2(
  'YOUR_CLIENT_ID',
  'YOUR_CLIENT_SECRET',
  'YOUR_REDIRECT_URI'
);
oauth2Client.setCredentials({ refresh_token: 'YOUR_REFRESH_TOKEN' });

const gmail = google.gmail({ version: 'v1', auth: oauth2Client });

async function downloadExcelFromGmail() {
  // 列出带Excel附件的邮件
  const res = await gmail.users.messages.list({
    userId: 'me',
    q: 'has:attachment filename:xlsx OR filename:xls'
  });

  if (!res.data.messages) return;
  for (const msg of res.data.messages) {
    const message = await gmail.users.messages.get({
      userId: 'me',
      id: msg.id,
      format: 'full'
    });

    // 筛选Excel格式附件
    const attachments = message.data.payload.parts.filter(part => {
      return part.filename && (part.filename.endsWith('.xlsx') || part.filename.endsWith('.xls'));
    });

    for (const att of attachments) {
      const attachmentData = await gmail.users.messages.attachments.get({
        userId: 'me',
        messageId: msg.id,
        id: att.body.attachmentId
      });
      // 解码base64url格式内容
      const decoded = Buffer.from(attachmentData.data.data, 'base64url');
      const savePath = path.join('你的本地文件夹路径', att.filename);
      fs.writeFileSync(savePath, decoded);
      console.log(`已保存附件：${savePath}`);
    }
  }
}

downloadExcelFromGmail().catch(err => console.error(err));

注意事项 #

• 需在Google Cloud平台正确配置OAuth2凭据，确保授权邮箱已启用Gmail API访问权限。
• 刷新令牌（refresh token）需通过首次授权流程获取，需妥善保存避免重复授权。
• 可根据需求调整搜索条件（如指定发件人、时间段、主题关键词），提升邮件筛选效率。

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