本文介绍如何在 Symfony 5.4 项目中可靠上传大型备份文件（如 5GB ZIP）至 Microsoft OneDrive，重点推荐使用成熟的 krizalys/onedrive-php-sdk，并提供认证配置、分块上传、错误处理与内存优化等关键实践。
本文介绍如何在 symfony 5.4 项目中可靠上传大型备份文件（如 5gb zip）至 microsoft onedrive，重点推荐使用成熟的 `krizalys/onedrive-php-sdk`，并提供认证配置、分块上传、错误处理与内存优化等关键实践。
在 Symfony 应用中上传超大文件（如 5GB 备份 ZIP）至 OneDrive，绝不能依赖常规表单上传或简单 cURL 请求——OneDrive REST API 明确要求对 >10 MB 文件采用 分块上传（Upload Session）机制，以规避超时、内存溢出与网络中断风险。官方 PHP SDK 尚未完全覆盖大文件流式上传场景，因此推荐使用社区维护成熟、符合 Microsoft Graph 协议的开源库：krizalys/onedrive-php-sdk。
该 SDK 基于 OneDrive API v1.0，原生支持分块上传（createUploadSession() + putRange()），并已通过大量生产环境验证。在 Symfony 5.4 中集成步骤如下：
1. 安装与基础配置
composer require krizalys/onedrive-php-sdk
在 .env 中配置应用凭据（需提前在 Azure Portal 注册应用，启用 Files.ReadWrite 权限）：
ONEDRIVE_CLIENT_ID=your-client-id ONEDRIVE_CLIENT_SECRET=your-client-secret ONEDRIVE_REDIRECT_URI=https://your-app.com/callback ONEDRIVE_TENANT_ID=common # 或具体租户 ID
2. 实现分块上传服务
// src/Service/OneDriveUploader.php
namespace App\Service;
use Krizalys\Onedrive\Onedrive;
use Krizalys\Onedrive\UploadSession;
class OneDriveUploader
{
private Onedrive $onedrive;
public function __construct(
string $clientId,
string $clientSecret,
string $redirectUri,
string $tenantId = 'common'
) {
$this->onedrive = new Onedrive([
'client_id' => $clientId,
'client_secret' => $clientSecret,
'redirect_uri' => $redirectUri,
'tenant_id' => $tenantId,
]);
}
public function uploadLargeFile(string $localPath, string $remotePath): bool
{
// 确保文件存在且可读
if (!is_file($localPath) || !is_readable($localPath)) {
throw new \InvalidArgumentException("Cannot read file: {$localPath}");
}
$fileSize = filesize($localPath);
$stream = fopen($localPath, 'rb');
if (!$stream) {
throw new \RuntimeException("Failed to open stream for {$localPath}");
}
try {
// 创建上传会话（自动处理认证）
$session = $this->onedrive->createUploadSession($remotePath);
// 分块上传（每块建议 10–60 MB，避免超时）
$chunkSize = 30 * 1024 * 1024; // 30 MB
$offset = 0;
while ($offset putRange($chunk, $offset, $fileSize);
$offset += strlen($chunk);
// 可选：记录进度或触发事件
echo sprintf("Uploaded %d/%d bytes\r", $offset, $fileSize);
flush();
}
return true;
} finally {
fclose($stream);
}
}
}
3. 在命令行中调用（推荐用于备份任务）
// src/Command/UploadBackupCommand.php
namespace App\Command;
use App\Service\OneDriveUploader;
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
#[AsCommand(name: 'app:upload:backup')]
class UploadBackupCommand extends Command
{
public function __construct(private OneDriveUploader $uploader)
{
parent::__construct();
}
protected function configure(): void
{
$this->addArgument('file', InputArgument::REQUIRED, 'Local ZIP backup path');
$this->addArgument('path', InputArgument::REQUIRED, 'Remote OneDrive path (e.g. /backups/site-2024.zip)');
}
protected function execute(InputInterface $input, OutputInterface $output): int
{
$localFile = $input->getArgument('file');
$remotePath = $input->getArgument('path');
try {
$this->uploader->uploadLargeFile($localFile, $remotePath);
$output->writeln("<info>✅ Upload completed: {$remotePath}</info>");
return Command::SUCCESS;
} catch (\Exception $e) {
$output->writeln("<error>❌ Upload failed: {$e->getMessage()}</error>");
return Command::FAILURE;
}
}
}
注意事项与最佳实践
- ✅ 认证持久化：首次运行需手动完成 OAuth 授权流程（SDK 提供
getAuthorizationUrl()和authenticate()方法），后续调用将复用刷新令牌；建议将 token 存储于加密数据库或 Symfony Vault。 - ✅ 内存安全：全程使用
fopen('rb')流式读取，避免file_get_contents()加载整个 5GB 文件到内存。 - ✅ 断点续传：
krizalys/onedrive-php-sdk的UploadSession支持从任意 offset 恢复，适合不稳定网络环境。 - ⚠️ 超时设置：PHP CLI 默认无超时，但需确保
max_execution_time = 0及default_socket_timeout足够长（建议 ≥ 3600）。 - ⚠️ OneDrive 配额与限制：单个文件上限为 250 GB，但上传会话有效期仅 24 小时，务必在超时前完成全部分块。
通过以上方案，你可在 Symfony 5.4 中构建健壮、可维护、生产就绪的大文件 OneDrive 上传能力，无需重复造轮子，专注业务逻辑与可靠性保障。
