TensorBoard依赖TensorFlow日志机制，需用tf.summary.create_file_writer写入events文件，路径须为绝对路径或稳定相对路径，且tensorboard --logdir必须指向含子目录的日志父目录；标量记录须在writer.as_default()上下文中指定正确step，图像/图/直方图等需显式调用对应API并注意格式与频率；多实验应使用唯一子目录名避免冲突，启动前应检查events文件是否存在及权限。
TensorBoard 不是独立工具，它依赖 TensorFlow 的日志写入机制；直接调用 tensorboard 命令却看不到指标，大概率是因为没正确生成 events.out.tfevents.* 文件，或者路径没对上。
训练时必须用 tf.summary.create_file_writer 写日志
TensorFlow 2.x 默认不自动记录指标，model.fit() 里加 TensorBoard 回调只是 shortcut，底层仍靠 tf.summary 写入。手动控制更灵活，也更容易排查问题：
- 必须在训练循环外创建
tf.summary.create_file_writer，且路径不能是相对路径（比如"logs"），推荐用绝对路径或确保当前工作目录稳定 - 每个要记录的标量必须在
with writer.as_default():上下文中调用tf.summary.scalar()，否则写不进文件 - 注意步数（
step）参数：传step=epoch * steps_per_epoch + batch_idx才能对齐时间轴，只传epoch会导致 loss 曲线被压缩成每轮一个点
示例片段：
writer = tf.summary.create_file_writer("/tmp/my_logs")
for epoch in range(10):
for batch_idx, (x, y) in enumerate(dataset):
# ... 训练逻辑
loss = compute_loss(...)
with writer.as_default():
tf.summary.scalar("loss", loss, step=epoch * steps_per_epoch + batch_idx)
tensorboard --logdir 路径必须指向日志目录的父级
常见错误是把 --logdir 指向具体 events 文件，比如 --logdir=/tmp/my_logs/events.out.tfevents.123 —— 这会启动失败，报 No dashboards are active。TensorBoard 实际扫描的是目录下所有子目录里的 events 文件：
立即学习“Python免费学习笔记（深入）”；
- 正确做法：日志目录结构应为
/tmp/my_logs/train/...、/tmp/my_logs/val/...，然后运行tensorboard --logdir=/tmp/my_logs - 如果只有一组日志，也建议建个子目录，比如
/tmp/my_logs/run_001/，避免 TensorBoard 把其他隐藏文件误判为日志源 - Windows 下路径带空格或中文容易出问题，优先用短英文路径
自定义指标和图像需显式启用插件
默认 TensorBoard 只显示 SCALARS（标量），像 IMAGES、GRAPHS、HISTOGRAMS 这些需要额外配置：
- 写图像要用
tf.summary.image()，且输入 tensor 必须是[batch, height, width, channels]形状，channels为 1 或 3，否则报InvalidArgumentError: You must feed a value for placeholder - 想看计算图，得在 eager mode 关闭后（即
tf.function内）记录，或用tf.summary.trace_on()+tf.summary.trace_export() - HISTOGRAMS 对梯度监控很有用，但写入频率别太高，否则日志体积暴涨——每 100 步记一次比每步都记更实际
多实验对比时别混用同一个 logdir
往同一个 logdir 下不同子目录写日志没问题，但若多个训练进程同时往同一子目录写 events 文件，会出现文件覆盖或读取错乱，TensorBoard 刷新后曲线跳变、数据缺失都是这个原因：
- 每次新实验生成唯一子目录名，比如用时间戳：
f"run_{int(time.time())}" - 不要依赖
os.makedirs(logdir, exist_ok=True)就完事，得确认子目录名不重复 - 如果用 Jupyter 启动 TensorBoard，记得关掉旧实例再开新的，否则端口冲突或缓存旧日志
真正麻烦的不是启动不起来，而是日志写进去了但 TensorBoard 没读到——往往因为路径层级不对、events 文件权限不足、或者训练中途崩溃导致文件未 flush。动手前先 ls -l 看一眼日志目录里有没有生成 events 文件，比反复刷新网页有效得多。
