本文详解在 nginx + php 环境（如树莓派）中，通过表单提交动态更新 json 文件的完整实现，涵盖常见语法错误修复、文件权限配置、json 写入健壮性处理及防止空白页跳转等关键实践。
本文详解在 nginx + php 环境（如树莓派）中，通过表单提交动态更新 json 文件的完整实现，涵盖常见语法错误修复、文件权限配置、json 写入健壮性处理及防止空白页跳转等关键实践。
在基于 Nginx 的轻量级 Web 部署（例如 Raspberry Pi 3B+ 运行 Nginx 1.18.0 + PHP-FPM）中，直接通过 PHP 向 JSON 文件写入数据是常见需求，但极易因语法错误、路径问题、权限限制或逻辑缺陷导致失败（如页面空白、文件未更新）。以下为经过验证的专业级解决方案。
✅ 核心问题与修正要点
原始代码存在两个关键错误：
- PHP 语法错误：'name'=>>$_POST['username'] 中多了一个 >，应为 'name'=>$_POST['username']；
- 架构冲突风险：将 HTML 表单（index.html）与处理逻辑（index.php）分离，并共用 index.php 作为入口，易引发重定向至空 PHP 脚本页面（即空白 index.php 响应），且缺乏表单提交状态反馈。
推荐采用「单文件混合方案」——将 HTML 前端与 PHP 后端逻辑统一于 index.php 中，既避免路由混乱，又便于状态控制与错误提示。
✅ 推荐实现：安全、可调试的单文件方案
<?php
$output = null;
if ($_SERVER['REQUEST_METHOD'] === 'POST' &&
isset($_POST['submit']) &&
!empty(trim($_POST['uuid'])) &&
!empty(trim($_POST['username']))) {
$filepath = 'whitelist.json';
// 初始化数据数组：若文件存在则读取并解码；否则创建空数组
$json_arr = file_exists($filepath) && is_readable($filepath)
? json_decode(file_get_contents($filepath), true)
: [];
// 验证 JSON 解码是否成功（防止损坏文件导致 null）
if (json_last_error() !== JSON_ERROR_NONE) {
$output = "⚠️ JSON 文件损坏，请手动检查 " . htmlspecialchars($filepath);
} else {
// 添加新条目（注意：使用 trim() 防止空格干扰）
$json_arr[] = [
'uuid' => trim($_POST['uuid']),
'name' => trim($_POST['username'])
];
// 使用 fopen + fwrite + JSON_PRETTY_PRINT 提升可读性与写入可靠性
$fp = fopen($filepath, 'w');
if ($fp === false) {
$output = "❌ 无法打开文件：" . htmlspecialchars($filepath) . "（检查目录写权限）";
} else {
$encoded = json_encode($json_arr, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);
if ($encoded === false) {
$output = "❌ JSON 编码失败：" . json_last_error_msg();
} else {
$bytes = fwrite($fp, $encoded);
fclose($fp);
$output = "✅ 成功写入！共 {$bytes} 字节 → <code>" . htmlspecialchars($filepath) . "</code>";
}
}
}
}
?>
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<title>白名单管理</title>
<style>
body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; margin: 4rem auto; max-width: 600px; padding: 0 1rem; }
.group { margin: 1rem 0; }
input[type="text"] { width: 100%; padding: 0.5rem; font-size: 1rem; border: 1px solid #ccc; border-radius: 4px; }
button { background: #007bff; color: white; border: none; padding: 0.6rem 1.2rem; border-radius: 4px; cursor: pointer; }
.message { margin-top: 1rem; padding: 0.5rem; border-radius: 4px; }
.success { background: #d4edda; color: #155724; border: 1px solid #c3e6cb; }
.error { background: #f8d7da; color: #721c24; border: 1px solid #f5c6cb; }
</style>
</head>
<body>
<h1>? 添加白名单用户</h1>
<form method="POST" autocomplete="off">
<div class="group">
<input type="text" name="uuid" placeholder="请输入 UUID（如：a1b2-c3d4-e5f6...）" required>
</div>
<div class="group">
<input type="text" name="username" placeholder="请输入用户名" required>
</div>
<button type="submit" name="submit">提交</button>
</form>
<?php if ($output): ?>
<div class="message <?= strpos($output, '✅') !== false ? 'success' : 'error' ?>">
<?= $output ?>
</div>
<?php endif; ?>
</body>
</html>⚠️ 关键注意事项与部署检查清单
- 文件系统权限：确保 Web 服务器用户（如 www-data）对 whitelist.json 所在目录拥有 写权限（推荐：chown www-data:www-data /var/www/html/ + chmod 755 /var/www/html/；JSON 文件初始可设 chmod 644，PHP 会自动更新）；
-
Nginx + PHP-FPM 配置验证：确认 nginx.conf 或站点配置中已正确启用 .php 处理，例如：
location ~ \.php$ { include snippets/fastcgi-php.conf; fastcgi_pass unix:/var/run/php/php7.4-fpm.sock; # 版本需匹配 } -
JSON 文件初始化：首次运行前，建议手动创建空 JSON 数组文件：
echo '[]' > /var/www/html/whitelist.json
-
安全性增强（生产环境必加）：
- 使用 filter_input() 替代裸 $_POST；
- 对 UUID/username 做格式校验（如正则）；
- 添加 CSRF Token（防止跨站请求伪造）；
- 将 JSON 文件移出 Web 可访问目录（如 /var/www/data/whitelist.json），并通过绝对路径写入。
✅ 总结
该方案通过单文件结构消除路由歧义，内建 JSON 解码容错、文件权限检测与用户友好的操作反馈，兼顾功能性与可维护性。只要确保 Nginx 正确代理 PHP 请求、目录具备写权限，即可稳定运行于树莓派等嵌入式 Nginx 环境。后续可轻松扩展为 API 接口或对接数据库，奠定可演进的数据管理基础。
立即学习“PHP免费学习笔记（深入）”；
