单台服务器必须将系统时区设为Asia/Shanghai，并在PHP入口或php.ini中设置date_default_timezone_set('Asia/Shanghai')，否则定时任务、日志、JWT等时间相关功能将异常。
单台服务器配置系统时区是 Hyperf 正常运行的关键前置步骤，尤其影响定时任务（Crontab）、日志时间戳、数据库写入时间及 JWT Token 过期判断等场景。Hyperf 本身不自动同步或覆盖系统时区，必须由操作系统层统一设定。
确认并设置系统时区
执行以下命令查看当前系统时区：
timedatectl status | grep "Time zone"
若显示 UTC 或非目标时区（如 America/New_York），需修正为 Asia/Shanghai（中国标准时间）：
sudo timedatectl set-timezone Asia/Shanghai
验证生效：
date # 应输出 CDT 或 CST 时间，且年月日时分秒正确
Hyperf 应用层同步时区配置
仅改系统时区还不够——PHP 进程默认可能仍使用 UTC，需在 Hyperf 中显式声明。编辑 config/autoload/crontab.php（定时任务）和 config/autoload/redis.php（如有依赖时间的缓存逻辑）等涉及时间的配置文件，确保关键位置指定时区：
-
在
config/autoload/crontab.php中设置：'timezone' => 'Asia/Shanghai',
在
config/autoload/redis.php的连接配置中，如使用predis或phpredis，无需额外设时区，但业务代码中调用date()或Carbon::now()前应确保 PHP 默认时区已设：
在 public/index.php 或 bin/hyperf.php 入口顶部添加（推荐统一入口处）：
date_default_timezone_set('Asia/Shanghai');也可在 php.ini 中全局设置（更稳妥）：
date.timezone = Asia/Shanghai
修改后重启 PHP CLI 环境（如已启用 opcache，需清空：sudo php -r "opcache_reset();"）。
验证部署是否生效
启动服务后，执行以下检查：
- 查看启动日志是否有
[INFO] Crontab manager started...，并确认后续任务执行时间与本地时间一致； - 写一个简单 Crontab 类（如每分钟输出
date('Y-m-d H:i:s')），观察控制台打印是否为北京时间； - 调用接口返回时间字段（如
/api/time返回date('c')），比对是否带+0800时区标识。
常见陷阱提醒
- 不要只改
config/autoload/crontab.php的timezone就认为万事大吉——PHP 进程本身的date_default_timezone_get()必须是Asia/Shanghai，否则Carbon、DateTime构造、数据库NOW()函数行为可能不一致； - Docker 部署时，需在
Dockerfile中显式设置时区：ENV TZ=Asia/Shanghai RUN ln -sf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone
- Ubuntu 22.04+ 默认使用 systemd-timesyncd，若服务器时间漂移严重，建议同时启用 NTP 同步：
sudo systemctl enable systemd-timesyncd sudo systemctl start systemd-timesyncd
时区配置完成后再启动 php bin/hyperf.php start，整个 Hyperf 应用的时间上下文就统一了。
