本文详解如何通过 php 正确下载 caiso oasis api 返回的 zip 文件（如 sld_fcst 数据），解决 `file_get_contents` 下载后文件损坏、路径错误及空文件等常见问题，并提供可直接运行的健壮示例代码。
CAISO OASIS（California Independent System Operator Open Access Same-Time Information System）采用传统 HTTP GET 接口返回 ZIP 压缩包（内含 CSV/XML 数据），其响应为二进制 ZIP 流，不依赖 Cookie 或会话，但对请求头、URL 编码和文件写入方式极为敏感。许多开发者误用 file_get_contents($url, "rb") —— 这里的 "rb" 并非模式参数，而是被当作 $context 的布尔值（等价于 true），导致 use_include_path=1 被意外启用，引发不可预知行为；更关键的是，file_put_contents() 的第一个参数必须是完整的目标文件路径（含文件名），而非仅目录路径，否则将报错 “No such file or directory”。
✅ 正确做法如下：
1. 构造合法 URL（避免手动拼接特殊字符）
CAISO 对时间格式（如 20220109T7:00-0000）和参数顺序无严格要求，但需确保 URL 完整且未被双重编码。推荐直接构建查询字符串，再用 http_build_query() 处理（自动编码）：
<?php
// 时间范围：30天前至昨日 7:00（PST）
$end = date('Ymd\TH:iO', strtotime('yesterday 7:00'));
$start = date('Ymd\TH:iO', strtotime('-30 days 7:00'));
$params = [
'startdatetime' => $start,
'enddatetime' => $end,
'resultformat' => '6', // CSV format
'queryname' => 'SLD_FCST',
'market_run_id' => 'ACTUAL',
'version' => '1'
];
$url = 'http://oasis.caiso.com/oasisapi/SingleZip?' . http_build_query($params);
?>2. 安全下载 ZIP 内容
使用 file_get_contents() 获取原始二进制数据（无需额外标志），并显式检查返回值：
对设计或页面进行 WCAG 2.1 AA 无障碍审计。触发关键词：“audit accessibility”、 “check a11y”、 “is this accessible?” 或在审查设计时使用。
立即学习“PHP免费学习笔记（深入）”；
$content = file_get_contents($url);
if ($content === false) {
throw new RuntimeException("Failed to fetch ZIP from CAISO: " . error_get_last()['message']);
}⚠️ 注意：file_get_contents() 默认以二进制安全方式读取，无需 "rb"；若需更高可靠性（如超时控制、错误重试），建议改用 cURL（见文末扩展说明）。
3. 正确写入 ZIP 文件（关键！）
file_put_contents() 第一个参数必须是带扩展名的完整文件路径（如 'data/sld_fcst_20220109_20220207.zip'），而非目录路径。同时确保目标目录存在且有写权限：
// ✅ 正确定义目标文件路径（含文件名）
$targetDir = __DIR__ . '/private/test/'; // 推荐使用 __DIR__ 替代复杂 SERVER 变量解析
$zipFilename = sprintf('sld_fcst_%s_%s.zip',
str_replace(['T', ':', '-'], '', $start),
str_replace(['T', ':', '-'], '', $end)
);
$fullPath = $targetDir . $zipFilename;
// 创建目录（递归）
if (!is_dir($targetDir)) {
mkdir($targetDir, 0755, true);
}
// 写入 ZIP 文件
if (file_put_contents($fullPath, $content) === false) {
throw new RuntimeException("Failed to write ZIP to: $fullPath");
}
echo "✅ ZIP downloaded successfully: $fullPath\n";4. （可选）解压并读取 CSV
下载成功后，可用 ZipArchive 解析内容：
$zip = new ZipArchive();
if ($zip->open($fullPath) === TRUE) {
for ($i = 0; $i < $zip->numFiles; $i++) {
$filename = $zip->getNameIndex($i);
if (pathinfo($filename, PATHINFO_EXTENSION) === 'csv') {
$csvContent = $zip->getFromIndex($i);
echo "Found CSV: $filename (" . strlen($csvContent) . " bytes)\n";
// 处理 $csvContent（如 fputcsv / str_getcsv）
}
}
$zip->close();
} else {
echo "⚠️ Failed to open ZIP archive.\n";
}? 关键注意事项总结
- ❌ 错误：file_put_contents('/path/to/dir/', $data) → 目录路径不合法
- ✅ 正确：file_put_contents('/path/to/dir/filename.zip', $data)
- ❌ 错误：file_get_contents($url, "rb") → "rb" 被误作布尔上下文
- ✅ 正确：file_get_contents($url)（默认二进制安全）
- ? 生产环境建议：添加 stream_context_create(['http' => ['timeout' => 60]]) 防止卡死
- ? 替代方案：cURL 更可控（支持 CURLOPT_FOLLOWLOCATION, CURLOPT_BINARYTRANSFER, 自定义 User-Agent）
通过以上步骤，即可稳定下载 CAISO OASIS 的 ZIP 数据，为后续自动化数据处理打下坚实基础。
