debugging-streamlit by streamlit/streamlit
npx skills add https://github.com/streamlit/streamlit --skill debugging-streamlitmake debug my_app.py
这将同时启动后端(Streamlit/Python)和前端(Vite/React)并启用热重载。启动时会打印应用 URL(默认为 http://localhost:3001;3000 端口保留给手动运行 make frontend-dev;如果其他调试会话正在运行,可能会使用 3002+ 端口)。除非有特定的硬性要求(最后手段),否则请避免固定 VITE_PORT。
热重载行为:
frontend/ 代码的更改会在几秒内生效。lib/streamlit/)的更改需要重启 。广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
make debug每次 make debug 运行都会将日志写入 work-tmp/debug/ 下每个会话的目录,并更新 work-tmp/debug/latest/ 指向最近的会话。由于 latest/* 是一个符号链接,它可能会移动,如果多个调试会话同时启动/停止——当你需要稳定的日志引用时,请优先使用 make debug 打印的会话目录路径。你可以在 make debug 启动输出的 Log files 部分找到确切的会话目录。
| 文件 | 内容 |
|---|---|
work-tmp/debug/latest/backend.log | Python print() 语句、Streamlit 日志、错误 |
work-tmp/debug/latest/frontend.log | 浏览器 console.log()、React 错误、Vite 输出 |
日志在每个会话开始时被清除,并在退出后保留以供事后分析。
日志大小警告: 在长时间的调试会话中,日志可能会变得很大。不要读取整个日志文件,而是使用 rg 搜索特定模式:
# 搜索特定的调试消息
rg "DEBUG:" work-tmp/debug/latest/backend.log
# 搜索错误(不区分大小写)
rg -i "error|exception|traceback" work-tmp/debug/latest/backend.log
# 带上下文搜索(前后 3 行)
rg -C 3 "my_function" work-tmp/debug/latest/backend.log
# 在前端日志中搜索特定组件
rg "MyComponent" work-tmp/debug/latest/frontend.log
使用此目录存放所有调试工件(脚本、截图等)以保持组织有序。
后端(Python):
print(f"DEBUG: session_state = {st.session_state}")
前端(TypeScript/React):
console.log("DEBUG: props =", props)
前端的 console.log() 输出会出现在 work-tmp/debug/latest/frontend.log(或当前会话的 frontend.log 文件)中。
work-tmp/debug/ 中创建或使用一个测试脚本(例如,work-tmp/debug/test_feature.py)make debug work-tmp/debug/test_feature.pywork-tmp/debug/latest/backend.log 中的 Error/Exception 和 work-tmp/debug/latest/frontend.log 中的控制台错误,以确保两个服务器都正确启动http://localhost:3001,但也可能是 3002+)work-tmp/debug/latest/backend.log 是否有任何错误work-tmp/debug/latest/backend.log 和 work-tmp/debug/latest/frontend.log 来监控日志快速错误检查:
# 后端错误
rg -i "error|exception" work-tmp/debug/latest/backend.log
# 前端控制台错误
rg -i "error" work-tmp/debug/latest/frontend.log
用于需要截图或自动化 UI 交互的高级调试。
对于简单的截图和交互,使用 @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.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) - 轮询直到条件为真Playwright API 参考:https://playwright.dev/python/docs/api/class-playwright
# 整页截图
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 正在运行且状态良好page.goto() 之后调用 wait_for_app_loaded(page)调试完成后,从 work-tmp/debug/ 中删除临时脚本和截图。
每周安装数
126
仓库
GitHub 星标数
44.0K
首次出现
2026年2月5日
安全审计
安装于
opencode120
github-copilot113
gemini-cli112
codex112
kimi-cli107
amp107
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/ code are applied within seconds.lib/streamlit/) require restarting make debug.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.
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).
work-tmp/debug/ (e.g., work-tmp/debug/test_feature.py)make debug work-tmp/debug/test_feature.pywork-tmp/debug/latest/backend.log for Error/Exception and work-tmp/debug/latest/frontend.log for console errors to ensure both servers started correctlyhttp://localhost:3001, but it may be 3002+)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
For advanced debugging with screenshots or automated UI interaction.
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.).
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()
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.
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 loadwait_for_app_run(page) - wait for script execution after interactionwait_until(page, fn, timeout) - poll until condition is truePlaywright API Reference : https://playwright.dev/python/docs/api/class-playwright
# 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")
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.3000 is reserved for manual make frontend-dev sessions.VITE_PORT=3002 make debug <app.py> (last resort).Hot-reload not working:
lib/streamlit/ require restarting make debug.work-tmp/debug/latest/frontend.log for Vite errors. TypeScript errors can break HMR.Playwright script fails to connect:
make debug is running and healthywait_for_app_loaded(page) is called after page.goto()After debugging is complete, remove temporary scripts and screenshots from work-tmp/debug/.
Weekly Installs
126
Repository
GitHub Stars
44.0K
First Seen
Feb 5, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
opencode120
github-copilot113
gemini-cli112
codex112
kimi-cli107
amp107
科学数据探索性分析工具:自动检测200+格式,生成EDA报告与可视化建议
1,000 周安装
AI邮件设计工具:使用inference.sh CLI生成高转化率营销邮件模板与布局指南
7,700 周安装
GitHub Copilot TLDR Prompt:AI助手快速生成技术文档摘要工具
7,700 周安装
Power Platform Dataverse Python SDK 解决方案架构师 - 业务用例构建与代码生成
7,700 周安装
OG 图片设计工具:一键生成社交分享图片,支持多平台尺寸规范
7,700 周安装
Google Workspace CLI 行政助理技能 | 高效管理高管日程、邮件与会议
7,800 周安装
Gmail过滤器创建教程 - 使用Google Workspace CLI自动分类邮件与添加标签
7,900 周安装
work-tmp/debug/latest/backend.logwork-tmp/debug/latest/backend.log and work-tmp/debug/latest/frontend.log