前端UI组件后端【免费下载链接】uppyThe next open source file uploader for web browsers :dog:项目地址https://gitcode.com/gh_mirrors/up/uppy点击查看免费下载本文以uppy/google-drive包的 CHANGELOG.md 为线索系统梳理该插件从 v2 到 v6 的关键技术演进TypeScript 重构、ESM 迁移、export maps、性能优化、插件类型注册等并深入其客户端源码与 Uppy Companion 服务端实现讲解插件如何接入 Google Drive、OAuth 鉴权、文件列表与下载的内部机制以及各版本升级对使用者的实际影响。一、插件是什么uppy/google-drive 的定位与整体架构uppy/google-drive是 Uppy 官方提供的「远程文件获取acquirer」插件让用户可以直接从自己的 Google Drive 账户中挑选文件并导入到 Uppy 的上传队列中随后交给 XHR Upload、TUS 等上传插件发送到目标服务器。其官方定位在 README.md 中描述为The Google Drive plugin for Uppy lets users import files from their Google Drive account。它的架构是典型的Uppy Companion 双层结构浏览器端本包负责渲染文件选择界面Provider Views、与 Uppy 核心交互、向 Companion 发起 API 请求服务端Companion负责完成 Google OAuth 鉴权、调用 Google Drive API v3 列出文件、下载/导出文件并转发给上传目的地。关键设计意图在 README 中写得非常清楚Companion 在服务端完成 Google 鉴权与文件下载可以节约用户带宽尤其对移动网络用户友好——文件流从 Google 直接到服务器而不是先下载到用户浏览器再上传。在浏览器端本包的核心实现文件为GoogleDrive.tsx插件主类继承自UIPlugin类型为acquirerDriveProviderViews.ts定制化的 Provider 视图处理团队盘选择逻辑locale.ts插件的默认本地化文案目前仅pluginNameGoogleDrive: Google Driveindex.ts包入口重新导出GoogleDriveOptions类型与默认插件类。服务端对应实现位于 packages/uppy/companion/src/server/provider/google/drive/index.ts 与 adapter.ts。二、快速上手安装、注册与最简配置安装npm install uppy/google-drive从该包的 package.json 可以看到其运行时依赖非常轻仅需preact用于渲染 UI并以uppy/core作为 peer dependency。构建与类型检查分别通过tsc --build tsconfig.build.json与tsc --build完成。注册插件import Uppy from uppy/core import GoogleDrive from uppy/google-drive const uppy new Uppy() uppy.use(GoogleDrive, { // Options })这是 README 中的最小示例。插件的完整选项类型定义如下见 GoogleDrive.tsxexport type GoogleDriveOptions CompanionPluginOptions { locale?: LocaleStringstypeof locale }其中CompanionPluginOptions由uppy/core/companion-client提供常用字段包括选项作用companionUrlCompanion 服务的 URL必须配置才能工作companionAllowedHosts允许通信的 Companion 域名白名单companionHeaders随请求发送到 Companion 的额外请求头companionKeysParamsOAuth 鉴权时所需的 key / credentialsName 参数companionCookiesRule控制跨域请求携带 Cookie 的规则locale覆盖插件的本地化文案插件构造时会对companionAllowedHosts做归一化处理getAllowedHosts并实例化Provider客户端其中显式声明了provider: drive与supportsRefreshToken: true见 GoogleDrive.tsx。supportsRefreshToken: true意味着当访问令牌过期时客户端会尝试通过刷新令牌重新获取而不是直接报错该逻辑见 Provider.ts。⚠️ 注意GoogleDrive 插件必须配合 Companion 服务端才能工作这一点在 README 中被反复强调A Companion instance is required for the GoogleDrive plugin to work.三、客户端源码剖析插件如何工作3.1 插件主类在 GoogleDrive.tsx 中GoogleDrive类继承了UIPlugin并实现了UnknownProviderPlugin接口。构造函数中依次完成设置插件类型为acquirer、插件 ID 默认为GoogleDrive使用tokenStorage作为默认令牌存储this.storage this.opts.storage || tokenStorage内联定义 Google Drive 的彩色 SVG 图标32×32归一化companionAllowedHosts并创建Provider实例初始化 i18n插件标题取自pluginNameGoogleDrive即 Google Drive。install()阶段会创建DriveProviderViews并传入两个重要选项this.view new DriveProviderViews(this, { provider: this.provider, loadAllFiles: true, virtualList: true, })这两个选项的含义可以追溯到 ProviderView.tsxloadAllFiles: true递归加载全部文件配合 Companion 的nextPagePath分页游标循环拉取这正是 CHANGELOG v3.2.0 中Load Google Drive / OneDrive lists 5-10x faster always load all files性能优化的客户端侧开关virtualList: true使用虚拟列表渲染即 Browser.tsx 中的virtualList标志文件很多时只渲染可视区域的行避免 DOM 节点爆炸。3.2 团队盘的特殊处理DriveProviderViews覆写了toggleCheckbox方法见 DriveProviderViews.tstoggleCheckbox(item, isShiftKeyPressed) { // We dont allow to check team drives; but we leave the checkboxes visible to show the partial state if (!item.data.custom?.isSharedDrive) { super.toggleCheckbox(item, isShiftKeyPressed) } }也就是说用户不能直接勾选整个团队盘Shared Drive但复选框仍然可见以展示部分选中状态。这一行为对应 issue #5232 的讨论是一个值得注意的产品细节。四、Companion 服务端Google Drive API 集成细节4.1 文件列表适配层做了什么Companion 的 Drive providerindex.ts使用 Google Drive API v3通过got客户端封装请求前缀为https://www.googleapis.com/drive/v3。列表接口list()会并行发起三个请求fetchSharedDrives()仅在根目录首页directory root !cursor调用/drives接口递归拉取所有团队盘pageSize: 100fetchFiles()调用/files接口查询语句为${directory} in parents) and trashedfalseShared with me 虚拟目录则使用sharedWithMe and trashedfalsepageSize: 1000并设置supportsAllDrives: truefetchAbout()调用/about获取当前用户邮箱用于显示用户名。文件字段通过fields参数精确控制DRIVE_FILES_FIELDS避免请求不必要的权限信息——代码注释指出不请求permissions字段才能把 pageSize 从 100 提升到 1000。4.2 适配器将 Google 响应转换为 Uppy 树结构adapter.ts 中的adaptData把 Drive API 的原始响应转换为 Uppy 的文件树节点包含以下关键映射getItemName为 G Suite 文件Google Docs / Sheets / Slides 等自动附加导出扩展名映射关系为application/vnd.google-apps.document→.docxapplication/vnd.google-apps.drawing→.pngapplication/vnd.google-apps.script→.jsonapplication/vnd.google-apps.spreadsheet→.xlsxapplication/vnd.google-apps.presentation→.pptgetMimeType如果是快捷方式shortcut则取其目标文件的 MIME 类型如果是 G Suite 文件则映射为导出类型getGsuiteExportType定义 G Suite 文件导出格式文档→Word、表格→Excel、演示→PPT、绘图→PNG、脚本→JSON兜底为 PDFgetItemIcon对普通文件将缩略图链接从s220缩小为s40对团队盘则用背景图生成小图标getItemSubList过滤掉无法导出的 G Suite 类型除白名单外避免列表中出现无法下载的条目VIRTUAL_SHARED_DIR shared-with-me在根目录虚拟出Shared with me文件夹置于列表最前面。4.3 下载与导出download()方法最终调用streamGoogleFileindex.ts核心逻辑是先getStats获取文件元信息若文件是 shortcut则递归获取其 target 的统计信息对 G Suite 文件优先使用 Google 提供的exportLinks避免大文件导出的 This file is too large to be exported. 问题否则调用/files/{id}/export?mimeType...对普通文件调用/files/{id}?altmedia流式下载全程通过prepareStream探测文件大小并以Readable流返回给上层由 Companion 转发到最终上传目的地。同时getStats中所有请求都带有supportsAllDrives: true保证能读取团队盘中的文件。五、版本演进时间线CHANGELOG 的核心变更解读以下按版本从早到晚梳理 CHANGELOG.md 中的关键变更并标注其对使用者的实际影响。v2.x模块化与文档规范化v2.0.52021-12Uppy v2.3.0随主仓库重构 locale 脚本生成了类型与文档#3276。v2.1.02022-05Uppy v2.10.0重构为 ESM#3683。此前 CommonJS 时代通过require()引入的方式在 v2.1.0 之后应改用import。v2.1.12022-05Uppy v2.11.0随各包统一更新打包器推荐#3763官方推荐使用支持 ESM 的现代打包器如 webpack 5、Vite、Rollup。v3.x进入 v3 主线的兼容调整v3.0.02022-08Uppy v3.0.0全面切换到 ESM。Uppy v3 是一个大版本换代所有包统一为 ESM-only。v3.0.1补齐各独立包的 CHANGELOG 缺失条目。v3.2.02023-07Uppy v3.12.0重大性能优化——Load Google Drive / OneDrive lists 5-10x faster always load all files#4513。这是上一节提到的loadAllFiles: true选项的来源文件列表加载提速 5–10 倍并且始终加载全部文件不再按页截断。v3.5.02024-03Uppy v3.24.0重构为 TypeScript#4979。这是该插件历史上的里程碑JavaScript 实现被 TypeScript 重写此后插件具备完整的类型定义GoogleDriveOptions等类型可以从包入口直接导入。v4.xTypeScript 深化与工程化v4.0.0-beta.12024-03v4 预览版延续 TypeScript 重构。v4.1.02024-08Uppy v4.3.0导出插件选项类型#5433。使用者可以import type { GoogleDriveOptions } from uppy/google-drive并在配置对象上获得完整的类型检查。v4.1.12024-10Uppy v4.6.0统一修复各包文档中的链接#5492。v4.2.02024-12Uppy v4.8.0清理各包 tsconfig#5520。v4.3.02025-01Uppy v4.11.0从所有包的 tsconfig 中移除paths#5572。v4.3.32025-05Uppy v4.16.0locale 字符串全部改为可选#5728。这意味着传入部分locale覆盖时不再需要补全所有文案字段对自定义多语言场景更友好。v4.4.0使用 TypeScript 编译器替代 Babel#0c24c5a进一步统一构建链。v4.4.2在 package.json 中定义files字段明确发布内容为src、lib、dist与CHANGELOG.md这正好解释了当前仓库中该包的目录结构。v5.xExport Maps 与插件类型注册v5.0.0为所有包引入 export maps#c5b51f6这是 v5 最大的破坏性变更影响有两处CSS 导入路径改变从uppy/google-drive/dist/styles.min.css变为uppy/google-drive/css/styles.min.css该包本身无样式但规则对所有包统一生效只能导入显式导出的东西之前像uppy/core/lib/foo.js这种内部路径导入将不再可用。v5.0.1从 package.json 中移除main字段因为export maps 已成为公共 API 的契约#975317d。v5.1.02025Uppy v5.x在uppy/core中新增PluginTypeRegistry 与类型化getPlugin重载#79e6460各包注册自己的插件 ID。反映在本包源码中就是 GoogleDrive.tsx 顶部的模块声明declare module uppy/core { export interface PluginTypeRegistryM extends Meta, B extends Body { GoogleDrive: GoogleDriveM, B } }效果是调用uppy.getPlugin(GoogleDrive)时无需再手动传泛型TypeScript 就能推断出具体的GoogleDrive插件类型。v6.x单一 Preact 版本保证v6.0.0当前版本从uppy/core的工具函数导入 Preact#84ad853保证整个 Uppy 生态使用同一个 Preact 版本避免多实例冲突——对应源码中的import { type ComponentChild, h } from uppy/core/utils/preact统一升级运行时共享依赖preact、nanoid、lodash、classnames、shallow-equal、pretty-bytes、p-queue、tus-js-client、transloadit/types、is-mobile、exifr、compressorjs、rxjs、tslib 等并附带uppy/companion的jwt.ts、request.ts类型修复以适配types/jsonwebtokenv9 与types/node依赖uppy/core6.0.0。六、升级迁移速查从旧版本升级到当前版本综合以上演进从旧版本升级时建议按以下清单核对模块系统v2.1.0 / v3.0.0 起确保使用 ESM 导入语法import GoogleDrive from uppy/google-drive打包器需支持 ESMCSS 路径v5.0.0 起若手动引入样式路径改为uppy/google-drive/css/styles.min.css本包无独立样式但同规则适用于所有 Uppy 包内部路径导入v5.0.0 起只使用包入口显式导出的 API不要依赖lib/、dist/下的内部文件类型导入v4.1.0 起配置类型使用import type { GoogleDriveOptions } from uppy/google-drive类型化 getPluginv5.1.0 起uppy.getPlugin(GoogleDrive)可直接获得具体类型无需泛型locale 覆盖v4.3.3 起只传需要覆盖的文案键即可无需补全全部字段依赖版本v6.0.0uppy/core需升级到 6.x。七、深入验证测试与调试线索如果你想在仓库中进一步验证上述实现可以从以下几个入口入手插件行为测试核心的 provider-views 渲染与分页逻辑测试位于 packages/uppy/core/test/provider-views/Companion 端测试Drive provider 的列表、下载与鉴权行为可参考 packages/uppy/companion/test/providers.test.ts 以及packages/uppy/companion/test/下的相关用例类型注册测试PluginTypeRegistry的用法可在 packages/uppy/core/test/types.test.ts 中查看示例工程React 示例 examples/react/src/RemoteSource.tsx、Vue 示例 examples/vue/src/RemoteSource.vue、Svelte 示例 examples/sveltekit/src/components/RemoteSource.svelte 都演示了如何组合多个远程源插件含 Google Drive到同一个 Uppy 实例。八、小结通过一条 CHANGELOG 的时间线我们完整还原了uppy/google-drive从 v2 到 v6 的工程化路径ESM 化 → TypeScript 重构 → export maps 契约化 → 插件类型注册 → 依赖统一。而在源码层面它又是一个典型的薄客户端 厚服务端远程源插件浏览器端只负责 UI 与请求编排OAuth、文件列表适配、G Suite 导出、流式下载全部由 Companion 承担。理解这两层各自的职责与演进脉络无论是对 Uppy 二次开发、自建 Companion 还是排查远程上传问题都会非常有帮助。赞分享前端UI组件后端【免费下载链接】uppyThe next open source file uploader for web browsers :dog:项目地址https://gitcode.com/gh_mirrors/up/uppy点击查看免费下载相关推荐tsParticles Absorbers 插件全解析从 CHANGELOG 演进史到源码实现与配置实战tsParticles Absorbers 插件全解析从 CHANGELOG 演进史到源码实现与配置实战 本篇技术指南以仓库中 plugins/absorbe前端Uppy 集成 Google Drive 文件导入uppy/google-drive 插件完整实战指南Uppy 集成 Google Drive 文件导入uppy/google drive 插件完整实战指南 本指南围绕 Uppy 官方远程来源插件 uppy/前端UI组件后端Blockly 连续工具箱插件 blockly/continuous-toolbox 演进全解析从 CHANGELOG 到源码实现Blockly 连续工具箱插件 blockly/continuous toolbox 演进全解析从 CHANGELOG 到源码实现 blockly/con前端低代码UI组件上一篇攻克CLIP模型训练数据路径配置难题从报错到精通的全流程解决方案下一篇JeecgBoot项目中的Vue路由刷新404问题分析与解决创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
