minio 官方客户端不支持直接在浏览器中运行，因其严重依赖 node.js 内置模块（如 `fs`、`crypto`、`http`）；正确做法是通过后端 api 中转，由服务端连接 minio，前端仅调用自有接口。
MinIO 是一个高性能、兼容 Amazon S3 的对象存储服务器，但其官方 JavaScript SDK（minio@7.1.1 及以上）专为 Node.js 环境设计，并非浏览器友好。它深度依赖 process, fs, crypto, stream, http, https, url, path 等 Node.js 核心模块——这些模块在 Webpack 5+ 构建的 React 应用（运行于浏览器）中根本不存在。即使你手动引入 buffer, stream-browserify 等 polyfill，仍会遇到类似 Uncaught ReferenceError: process is not defined 的错误，根本原因在于：Webpack 5 默认移除了对 Node.js 核心模块的自动 polyfill 支持，且部分模块（如 fs）在浏览器中无法真正模拟。
✅ 正确实践方案：前后端分离 + API 代理
你需要构建一个轻量后端服务（例如 Express.js），作为 MinIO 的“代理网关”：
// server.js（Express 示例）
const express = require('express');
const Minio = require('minio');
const app = express();
const minioClient = new Minio.Client({
endPoint: 'play.min.io',
port: 443,
useSSL: true,
accessKey: 'Q3AM3UQ867SPQQA43P2F',
secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG',
});
app.get('/api/presigned-url/:bucket/:object', async (req, res) => {
try {
const { bucket, object } = req.params;
const url = await minioClient.presignedGetObject(bucket, object, 24 * 60 * 60); // 24h
res.json({ url });
} catch (err) {
res.status(500).json({ error: err.message });
}
});
app.listen(4000, () => console.log('API server running on http://localhost:4000'));前端 React 中只需发起标准 HTTP 请求，无需安装 minio 包：
// src/hooks/useMinio.ts
import { useState } from 'react';
export function useMinio() {
const [loading, setLoading] = useState(false);
const [error, setError] = useState<string | null>(null);
const getPresignedUrl = async (bucket: string, object: string) => {
setLoading(true);
try {
const res = await fetch(`/api/presigned-url/${bucket}/${object}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
return data.url;
} catch (err) {
setError(err instanceof Error ? err.message : 'Failed to fetch URL');
throw err;
} finally {
setLoading(false);
}
};
return { getPresignedUrl, loading, error };
}⚠️ 关键注意事项：
- 绝不暴露 MinIO 凭据到前端：accessKey 和 secretKey 必须严格保留在服务端环境变量中（如 process.env.MINIO_ACCESS_KEY）；
- 避免直传敏感操作：如 putObject、removeObject 等写操作，应在后端封装鉴权逻辑（例如校验 JWT、检查用户权限）；
- 推荐使用预签名 URL（Presigned URL）：适用于安全地授予临时读/写权限，无需前端接触 MinIO SDK；
- 若必须前端直连（极少数场景），请改用 MinIO 的 Browser JS Client（已废弃，不推荐）或考虑替代方案（如 TUS 协议上传 + 后端回调）。
总结：React 前端 ≠ Node.js 运行时。拥抱分层架构——让 MinIO 与后端对话，让前端与你的 API 对话。这不仅解决技术兼容性问题，更是保障密钥安全、实现权限可控、提升系统可维护性的最佳实践。
立即学习“前端免费学习笔记（深入）”；
