Streamlit配置config.toml后Web应用自定义主题未生效问题

按优先级从高到低排查以下高频问题：

• 校验文件路径与命名合规性
  • .streamlit 文件夹必须放在项目根目录，和Streamlit入口启动文件（通常是app.py/streamlit_app.py）处于同一层级，不能嵌套在子目录内；注意目录名必须以半角点开头，不要拼错成streamlit、.stream_list这类错误名称。
  • 配置文件必须命名为config.toml，注意大小写敏感（Linux部署环境下大写后缀会无法识别），同时要关闭Windows系统的“隐藏已知文件扩展名”选项，避免文件实际被命名为config.toml.txt导致无法读取。
  • 检查.gitignore规则，确认没有把.streamlit目录或者.toml后缀文件加入忽略列表，否则本地配置不会被推送到代码仓库，部署环境自然读不到配置。
• 校验配置内容合法性
  • 检查TOML语法：确认所有符号都是半角英文，没有中文引号、全角等号、不可见特殊字符，合法的配置块结构参考如下：

    [theme]
    base="dark"
    primaryColor="#213767"
    backgroundColor="#13710d"
    font="monospace"
    

  • 检查色值格式：所有颜色参数必须是合法的十六进制RGB色值，少位、带非十六进制字符会导致整个[theme]配置块失效。
  • 排查代码优先级冲突：如果Python代码里用st.set_page_config手动指定了主题相关参数，代码内配置的优先级高于config.toml，会覆盖文件配置。
• 排除缓存类问题
  • 本地先验证：在项目根目录启动应用，点击右上角菜单→Settings→Theme，查看是否识别到自定义主题，如果本地都不生效，优先回到前两步排查路径和配置错误。
  • 部署环境操作：如果本地验证正常、云端部署不生效，先在Streamlit Cloud控制台对应用执行Full Reboot全量重启，普通的代码增量更新不会主动重载主题配置。
  • 前端缓存清理：重启应用后用Ctrl+F5（Windows）/Cmd+Shift+R（Mac）强制刷新浏览器，避免旧样式缓存覆盖新配置。
• 兜底验证方案
  如果以上步骤排查完还是不生效，可以直接在Streamlit Cloud的应用设置→Theme面板，手动把你配置的主题参数填入保存，如果手动填写后主题生效，说明问题100%出在仓库内config.toml的路径、提交状态上，重新核对文件位置、推送到正确的部署分支即可。

内容的提问来源于stack exchange，提问作者Jensen Holm