本地运行与调试：Shiny应用的文件结构、runApp()函数的用法、浏览器调试技巧

说实话，我第一次接触Shiny的时候，光看那个文件结构就懵了半天。后来自己折腾几个项目，踩过坑才摸清门道。这一节咱们就把本地运行和调试那点事儿讲透。你只要有RStudio或者命令行，就能跟着我走一遍。

Shiny应用的文件结构

一个标准的Shiny应用，说白了就两种组织方式：单文件模式和双文件模式。我推荐新手先从单文件开始，逻辑都在一块儿，调试起来方便。

文件/目录	作用	说明
app.R	单文件应用	包含 ui 和 server 两部分，适合小应用
ui.R	UI 定义	双文件模式下单独存放界面代码
server.R	服务器逻辑	双文件模式下单独存放响应逻辑
www/	静态资源	放 CSS、JavaScript、图片等，Shiny 自动托管
R/	辅助函数	可选，放自定义 R 函数文件，自动加载
data/	数据文件	可选，放 CSV、RDS 等数据

嗯，这里要注意：www 目录的名字不能改，Shiny 就认这个。我见过有人改成 resources，结果图片死活加载不出来，排查了半天。

runApp() 函数的用法

本地启动应用全靠 runApp()。你可以在 RStudio 点那个绿色的 Run App 按钮，但说实话，命令行里跑更能自定义。我一般这么写：

# 最简形式，在当前目录找 app.R
runApp()

# 指定应用路径
runApp("path/to/myapp")

# 指定 host 和 port，方便局域网访问
runApp(host = "0.0.0.0", port = 3838)

# 设置启动时自动打开浏览器
runApp(launch.browser = TRUE)

# 显示模式：normal / showcase / auto
runApp(display.mode = "showcase")

你看，host = "0.0.0.0" 这招很实用。你部署到服务器之前，先在本地用这个参数启动，然后局域网里其他设备都能访问，相当于提前做集成测试。我在项目里经常这样干，方便给同事预览。

还有 display.mode = "showcase"，它会显示代码和界面并排，特别适合做演示或者教学。但别在生产环境用，性能会打折扣。

浏览器调试技巧

本地跑起来之后，真正的调试才刚开始。浏览器就是你的主力工具。我打开 Chrome 开发者工具（F12）的步骤都快成肌肉记忆了。

1. 查看 Console 日志 —— R 端报错会打印到 RStudio 控制台，但前端 JavaScript 错误只会出现在浏览器 Console 里。比如 Shiny 的 showNotification() 如果没触发，先看 Console 有没有报错。
2. Network 面板 —— 看 WebSocket 连接状态。Shiny 用 WebSocket 通信，如果连接断掉，页面会卡死。刷新一下，看 ws 请求是不是 101 状态。
3. Elements 面板 —— 检查 HTML 结构。Shiny 自动生成的 <div id=“shiny-notification-panel”> 有没有出现在 DOM 里？没有的话说明渲染出问题了。
4. Sources 面板 —— 打断点。Shiny 的 JavaScript 文件可以设置断点，跟踪数据流。

还有一个神器叫 shiny::reactlog()。你可以在应用运行过程中调用它，它会生成一个交互式的响应图，展示每个 reactive 表达式的依赖关系和触发时机。

# 在 R 控制台运行
library(shiny)
reactlog::reactlog_enable()
# 然后正常启动 app，操作几下
# 再跑这个命令查看
shiny::reactlog()

为什么推荐它？因为 Shiny 的响应式系统有时像黑盒，你调一个 reactiveVal()，它会不会连带更新其他输出？肉眼看不出来。用 reactlog 就一目了然。我调试复杂应用的时候必开这个。

文件结构与调试流程全景

下面这张图把本章核心串起来了。从左到右，从文件组织到启动运行，再到浏览器调试和可视化分析，你照着这个流程走，本地调试基本不会卡住。

行了，理解文件结构，掌握 runApp()，再学会用浏览器和 reactlog 定位问题，本地跑 Shiny 应用就不会抓瞎了。试试看，把今天学的在自己电脑上走一遍。