Streamlit 应用调试指南：快速定位前后端错误与日志分析

debugging-streamlit by streamlit/streamlit

164 周安装量

44,100 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/streamlit/streamlit --skill debugging-streamlit

Python Web框架数据可视化调试

🇨🇳中文介绍

调试 Streamlit 应用

快速开始

make debug my_app.py

这将同时启动后端（Streamlit/Python）和前端（Vite/React）并启用热重载。启动时会打印应用 URL（默认为 http://localhost:3001；3000 端口保留给手动运行 make frontend-dev；如果其他调试会话正在运行，可能会使用 3002+ 端口）。除非有特定的硬性要求（最后手段），否则请避免固定 VITE_PORT。

热重载行为：

前端：对 frontend/ 代码的更改会在几秒内生效。
后端：只有对应用脚本的更改会触发重新运行。对 Streamlit 库本身（lib/streamlit/）的更改需要重启。

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

文件	内容
`work-tmp/debug/latest/backend.log`	Python `print()` 语句、Streamlit 日志、错误
`work-tmp/debug/latest/frontend.log`	浏览器 `console.log()`、React 错误、Vite 输出

用于截图和测试的临时 Playwright 脚本

用于需要截图或自动化 UI 交互的高级调试。

快速：Playwright CLI

对于简单的截图和交互，使用 @playwright/cli（在前端 devDependencies 中可用）：

cd frontend
STREAMLIT_APP_URL=http://localhost:3001
yarn playwright-cli open "$STREAMLIT_APP_URL"
yarn playwright-cli screenshot --filename ../work-tmp/debug/screenshot.png --full-page
yarn playwright-cli close

更多命令（snapshot、click、fill 等）请参见 https://github.com/microsoft/playwright-cli。

对于复杂的交互，在 work-tmp/debug/ 中创建临时的 Playwright 脚本：

# work-tmp/debug/debug_screenshot.py
"""Temporary Playwright script for debugging - run against make debug."""
import os
from playwright.sync_api import sync_playwright, expect

from e2e_playwright.shared.app_utils import get_text_input, click_button
from e2e_playwright.conftest import wait_for_app_loaded, wait_for_app_run


def main():
    app_url = os.environ.get("STREAMLIT_APP_URL", "http://localhost:3001")
    with sync_playwright() as p:
        browser = p.chromium.launch(headless=True)
        page = browser.new_page(viewport={"width": 1280, "height": 720})

        # Connect to app started with `make debug`
        page.goto(app_url)
        wait_for_app_loaded(page)

        # Interact with the app
        text_input = get_text_input(page, "Name")
        text_input.fill("Test User")
        click_button(page, "Submit")
        wait_for_app_run(page)

        # Verify and screenshot
        expect(page.get_by_text("Hello, Test User")).to_be_visible()
        page.screenshot(path="work-tmp/debug/debug_screenshot.png", full_page=True)
        print("Screenshot saved to work-tmp/debug/debug_screenshot.png")

        browser.close()


if __name__ == "__main__":
    main()

确保 make debug <app.py> 首先正在运行（如果需要，可以在后台任务中启动它）。如果你的 make debug 会话使用了非默认端口，请相应地设置 STREAMLIT_APP_URL，然后运行 Playwright 脚本：

STREAMLIT_APP_URL=http://localhost:3001 \
PYTHONPATH=. uv run python work-tmp/debug/debug_screenshot.py

这使用了 uv 管理的环境，包含所有依赖项（playwright 等），并且无需路径操作即可导入 e2e_playwright。

来自 e2e_playwright 的可用工具

元素定位器与交互（e2e_playwright.shared.app_utils）：提供诸如 get_text_input()、get_button()、click_button()、get_checkbox() 等辅助函数。

同步（e2e_playwright.conftest）：

wait_for_app_loaded(page) - 等待初始加载
wait_for_app_run(page) - 等待交互后的脚本执行
wait_until(page, fn, timeout) - 轮询直到条件为真

# 整页截图
page.screenshot(path="work-tmp/debug/full.png", full_page=True)

# 元素截图
element = page.get_by_test_id("stDataFrame")
element.screenshot(path="work-tmp/debug/dataframe.png")

端口已被占用 / 多个会话：

make debug 将自动选择一个空闲的前端端口（通常在 3001-3100 范围内），以便多个调试会话可以同时运行。
前端端口 3000 保留给手动 make frontend-dev 会话。
如果你对特定前端端口有硬性要求，可以使用 VITE_PORT=3002 make debug <app.py> 来固定它（最后手段）。

热重载不工作：

后端：只监视应用脚本。对 lib/streamlit/ 的更改需要重启 make debug。
前端：检查 work-tmp/debug/latest/frontend.log 中的 Vite 错误。TypeScript 错误可能会破坏 HMR。

Playwright 脚本连接失败：

验证 make debug 正在运行且状态良好
检查打印的应用 URL 是否可以在浏览器中访问
确保在 page.goto() 之后调用 wait_for_app_loaded(page)

调试完成后，从 work-tmp/debug/ 中删除临时脚本和截图。

understanding-streamlit-architecture skill：用于在调试跨层问题时更深入地理解后端/前端内部结构

🇺🇸English

Debugging Streamlit Apps

Quick Start

make debug my_app.py

This starts both backend (Streamlit/Python) and frontend (Vite/React) with hot-reload. The app URL is printed on startup (default http://localhost:3001; 3000 is reserved for manual make frontend-dev; it may use 3002+ if other debug sessions are running). Avoid pinning VITE_PORT unless you have a specific hard requirement (last resort).

Hot-reload behavior:

Frontend : Changes to frontend/ code are applied within seconds.
Backend : Only changes to the app script trigger a rerun. Changes to the Streamlit library itself (lib/streamlit/) require restarting make debug.

Log Files

Each make debug run writes logs to a per-session directory under work-tmp/debug/ and updates work-tmp/debug/latest/ to point at the most recent session. Because latest/* is a symlink, it can move if multiple debug sessions are starting/stopping concurrently—prefer using the session directory path printed by make debug when you need stable log references. You can find the exact session directory in the make debug startup output under the Log files section.

File	Content
`work-tmp/debug/latest/backend.log`	Python `print()` statements, Streamlit logs, errors
`work-tmp/debug/latest/frontend.log`	Browser `console.log()`, React errors, Vite output

Logs are cleared at the start of each session and persist after exit for post-mortem analysis.

Log size warning: Logs can grow large during extended debugging sessions. Instead of reading entire log files, use rg to search for specific patterns:

# Search for specific debug messages
rg "DEBUG:" work-tmp/debug/latest/backend.log

# Search for errors (case-insensitive)
rg -i "error|exception|traceback" work-tmp/debug/latest/backend.log

# Search with context (3 lines before/after)
rg -C 3 "my_function" work-tmp/debug/latest/backend.log

# Search frontend logs for specific component
rg "MyComponent" work-tmp/debug/latest/frontend.log

Use this directory for all debugging artifacts (scripts, screenshots, etc.) to keep them organized.

Adding Debug Output

Backend (Python):

print(f"DEBUG: session_state = {st.session_state}")

Frontend (TypeScript/React):

console.log("DEBUG: props =", props)

Frontend console.log() output appears in work-tmp/debug/latest/frontend.log (or the current session's frontend.log file).

Workflow

Create or use a test script in work-tmp/debug/ (e.g., work-tmp/debug/test_feature.py)
Run make debug work-tmp/debug/test_feature.py
Verify startup : Check work-tmp/debug/latest/backend.log for Error/Exception and work-tmp/debug/latest/frontend.log for console errors to ensure both servers started correctly
Access the printed App URL in your browser (default http://localhost:3001, but it may be 3002+)
Verify script execution : Check again for any errors after the first app access

Quick error check:

# Backend errors
rg -i "error|exception" work-tmp/debug/latest/backend.log

# Frontend console errors
rg -i "error" work-tmp/debug/latest/frontend.log

Temporary Playwright Scripts for Screenshots & Testing

For advanced debugging with screenshots or automated UI interaction.

Quick: Playwright CLI

For simple screenshots and interactions, use @playwright/cli (available in frontend devDependencies):

cd frontend
STREAMLIT_APP_URL=http://localhost:3001
yarn playwright-cli open "$STREAMLIT_APP_URL"
yarn playwright-cli screenshot --filename ../work-tmp/debug/screenshot.png --full-page
yarn playwright-cli close

See https://github.com/microsoft/playwright-cli for more commands (snapshot, click, fill, etc.).

Custom Scripts

For complex interactions, create temporary Playwright scripts in work-tmp/debug/:

# work-tmp/debug/debug_screenshot.py
"""Temporary Playwright script for debugging - run against make debug."""
import os
from playwright.sync_api import sync_playwright, expect

from e2e_playwright.shared.app_utils import get_text_input, click_button
from e2e_playwright.conftest import wait_for_app_loaded, wait_for_app_run


def main():
    app_url = os.environ.get("STREAMLIT_APP_URL", "http://localhost:3001")
    with sync_playwright() as p:
        browser = p.chromium.launch(headless=True)
        page = browser.new_page(viewport={"width": 1280, "height": 720})

        # Connect to app started with `make debug`
        page.goto(app_url)
        wait_for_app_loaded(page)

        # Interact with the app
        text_input = get_text_input(page, "Name")
        text_input.fill("Test User")
        click_button(page, "Submit")
        wait_for_app_run(page)

        # Verify and screenshot
        expect(page.get_by_text("Hello, Test User")).to_be_visible()
        page.screenshot(path="work-tmp/debug/debug_screenshot.png", full_page=True)
        print("Screenshot saved to work-tmp/debug/debug_screenshot.png")

        browser.close()


if __name__ == "__main__":
    main()

Running Temporary Scripts

Ensure make debug <app.py> is running first (start it in a background task if needed). If your make debug session is using a non-default port, set STREAMLIT_APP_URL accordingly, then run the Playwright script:

STREAMLIT_APP_URL=http://localhost:3001 \
PYTHONPATH=. uv run python work-tmp/debug/debug_screenshot.py

This uses the uv-managed environment with all dependencies (playwright, etc.) and makes e2e_playwright importable without path manipulation.

Available Utilities from e2e_playwright

Element Locators & Interactions (e2e_playwright.shared.app_utils): Provides helpers like get_text_input(), get_button(), click_button(), get_checkbox(), etc.

Synchronization (e2e_playwright.conftest):

wait_for_app_loaded(page) - wait for initial load
wait_for_app_run(page) - wait for script execution after interaction
wait_until(page, fn, timeout) - poll until condition is true

Playwright API Reference : https://playwright.dev/python/docs/api/class-playwright

Screenshot Best Practices

# Full page screenshot
page.screenshot(path="work-tmp/debug/full.png", full_page=True)

# Element screenshot
element = page.get_by_test_id("stDataFrame")
element.screenshot(path="work-tmp/debug/dataframe.png")

Troubleshooting

Port already in use / multiple sessions:

make debug will automatically pick a free frontend port (typically in the 3001-3100 range) so multiple debug sessions can run simultaneously.
Frontend port 3000 is reserved for manual make frontend-dev sessions.
If you have a hard requirement for a specific frontend port, you can pin it with VITE_PORT=3002 make debug <app.py> (last resort).

Hot-reload not working:

Backend: Only the app script is watched. Changes to lib/streamlit/ require restarting make debug.
Frontend: Check work-tmp/debug/latest/frontend.log for Vite errors. TypeScript errors can break HMR.

Playwright script fails to connect:

Verify make debug is running and healthy
Check the printed App URL is accessible in the browser
Ensure wait_for_app_loaded(page) is called after page.goto()

Cleanup

After debugging is complete, remove temporary scripts and screenshots from work-tmp/debug/.

Related Skills

understanding-streamlit-architecture skill: For deeper understanding of backend/frontend internals when debugging cross-layer issues

Weekly Installs

126

Repository

streamlit/streamlit

GitHub Stars

44.0K

First Seen

Feb 5, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode120

github-copilot113

gemini-cli112

codex112

kimi-cli107

amp107

科学数据探索性分析工具：自动检测200+格式，生成EDA报告与可视化建议

1,000 周安装

work-tmp/debug/latest/backend.log

Monitor logs by inspecting work-tmp/debug/latest/backend.log and work-tmp/debug/latest/frontend.log

Edit code - changes apply automatically via hot-reload

Check logs for debug output

Streamlit 应用调试指南：快速定位前后端错误与日志分析

🇨🇳中文介绍

调试 Streamlit 应用

快速开始

相关 Skills

日志文件

添加调试输出

工作流程