Bokeh 开发环境搭建完全指南从 conda 环境到本地 BokehJS 的逐步配置【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokehBokeh 是一个由两部分组成的交互式数据可视化项目用 Python 编写的 Bokeh 包源码以及用 TypeScript 编写的 BokehJS 客户端库。因此要为 Bokeh 贡献代码需要同时搭建 Python 与 TypeScript 两套开发环境。本文基于官方开发者指南的 setup 章节完整梳理从环境检查、Fork 克隆、conda 环境创建、npm 依赖安装、pre-commit 钩子配置、本地构建安装到环境变量与验证测试的全流程并结合仓库源码说明每一步的底层机制与常见故障排查方法。读完本文你将掌握一套可复现、可调试、可验证的 Bokeh 本地开发环境搭建方案。1. 前置准备检查 Git 与 conda安装或更新 GitBokeh 的源码存储在 Git 版本控制仓库中因此第一步是安装或更新 Git。不同平台Windows、macOS、Linux的安装方式不同可参考官方 Git 安装文档。如果你是 Git 新手建议先从官方文档的入门教程学起。安装或更新 conda开发 Bokeh 不仅需要 Python 包还需要若干非 Python 软件包例如用于 TypeScript 开发的 Node.js以及用于测试与导出的 Selenium。为了在同一个地方统一管理 Python 与非 Python 依赖Bokeh 使用 conda 包管理器。conda 是免费的 Anaconda Python 发行版的一部分适用于 Windows、macOS 与 Linux它能创建并管理虚拟环境因此你不需要venv、virtualenv或pipenv这类工具。虽然不装 conda 也可以手动安装所有依赖但本文的指南默认你已经安装了 conda。如果系统已安装 conda请先确保它是最新版本conda update -n base -c defaults conda2. Fork 并克隆仓库Bokeh 的源码托管在 GitHubhttps://github.com/bokeh/bokeh。除非你是 Bokeh 开发团队成员否则需要先 Fork 主仓库。Fork 时注意取消勾选“仅复制某个分支”例如 Copy the branch-3.2 branch only的选项以便获得完整的标签tags历史——这一点很关键因为后续本地构建依赖完整的 git tag详见 setup.py 中的check_tags()检查它要求至少 5 个 tag否则构建会中止。然后克隆到本地并将官方仓库添加为 upstream# SSH 方式 git remote add upstream gitgithub.com:bokeh/bokeh.git git fetch upstream # HTTPS 方式 git remote add upstream https://github.com/bokeh/bokeh.git git fetch upstream克隆完成后本地会出现一个bokeh目录下文称其为source checkout源码检出目录。3. 创建 conda 环境使用测试环境文件创建环境Bokeh 仓库的conda目录下存放着按 Python 版本区分的“测试环境文件”其中包含自动创建基础开发环境所需的全部依赖信息。在 source checkout 的根目录执行conda env create即可。例如安装 Python 3.12 的环境conda env create -n bkdev -f conda/environment-test-3.12.yml-n bkdev指定环境名为bkdev本文其余章节及开发者指南都默认使用这个名字。创建完成后激活环境conda activate bkdev环境文件里有什么以 conda/environment-test-3.12.yml 为例该文件不仅包含 Bokeh 运行时依赖如contourpy、jinja2、numpy、pandas、tornado、pyyaml等还包含一整套开发与测试工具包括TypeScript 工具链nodejs 24.*代码质量工具isort 5.8、pre-commit以及通过 pip 安装的ruff 0.15.*、mypy、pyright、vermin测试框架pytest 7.0、pytest-xdist、pytest-asyncio、pytest-tornado、coverage等浏览器测试与导出firefox 96、geckodriver、selenium 4.2以及 pip 安装的playwright、pytest-playwright示例运行依赖cartopy、flask、scikit-learn、sympy等文档构建依赖sphinx 9.*、pydata_sphinx_theme、sphinx-design等也就是说一条命令就能把 Python 环境、Node.js 环境、测试与文档工具全部装齐。更新环境每当上游环境文件变更例如主仓库更新了依赖或你切换到不同分支处理不同 issue 时需要更新本地环境conda env update --name bkdev -f conda/environment file更多关于创建与管理 conda 环境的内容可参考 conda 官方文档的 Managing environments 章节。4. 安装 Node 包构建 BokehJS 还需要用 npm 安装 JavaScript 依赖。如果按照上面的步骤用 conda 创建了环境npm 和 node.js 已经被 conda 安装到系统里了。Bokeh 通常要求 npm 的最新主版本。从 source checkout 顶层进入bokehjs子目录并全局升级 npmcd bokehjs npm install --locationglobal npm如果不想全局安装 npm可以去掉--locationglobal参数但后续所有npm命令都需要改用bokehjs/node_modules下的本地版本。然后仍在bokehjs子目录中安装 BokehJS 的全部 JavaScript 依赖npm ci该命令会把所需包安装到node_modules子目录。npm ci依据 bokehjs/package.json 中的锁文件做一次性干净安装通常只需在首次搭建环境时执行一次当依赖新增或变更时需要重新执行上述步骤。5. 配置 pre-commit 钩子Bokeh 使用 pre-commit 帮助你在提交时避免常见错误。在 source checkout 顶层执行python tools/hooks/install.py该脚本底层实际执行的是pre-commit install --install-hooks --hook-type pre-push见 tools/hooks/install.py会配置两个 Git 钩子在向 GitHub 推送提交时检查代码代码库测试codebase testspre-push 时运行 Bokeh 的代码库测试检查空白字符、import 顺序等代码质量问题涉及 Ruff、ESLint、isort 等工具受保护分支检查protected branches防止你误把提交推送到受保护的main和branch-x.y分支。从 .pre-commit-config.yaml 可以看到完整的钩子清单除 Ruff 检查、pyproject 校验、YAML/JSON 校验外还包括本地钩子run-code-qualitypytest 运行tests/codebase/test_code_quality.py、run-eslint、run-isort、run-ruff、run-vermin、validate-license、check-exclusions、check-optimized、check-windows-filenames以及protect-branches调用 tools/hooks/protect_branches.py。运行这些测试可能需要几十秒。如果测试失败检查控制台输出通常会给出需要修改的具体信息。卸载钩子则执行python tools/hooks/uninstall.py对应脚本执行的是pre-commit uninstall -t pre-push见 tools/hooks/uninstall.py。6. 本地构建与安装依赖全部就绪后最简单的构建安装方式是使用 pippip 在 conda 环境创建时已自动安装。运行 pip 前务必先激活bkdev环境。有两种本地安装方式命令行为适用场景pip install -e .以可编辑editable方式安装Python 源码改动即时生效无需重新安装推荐适合在 Bokeh 代码库上日常开发pip install .安装到本地site-packages修改 Python 源码后必须重新运行pip install .才生效一次性安装这两种命令在安装时都会同时构建并安装本地 BokehJS。如果希望跳过重新构建、直接使用其他本地版本可以设置BOKEHJS_ACTION环境变量BOKEHJS_ACTIONinstall pip install -e .从 setup.py 的实现可以看出BOKEHJS_ACTION的三种取值默认未设置等价于build先执行node make build在bokehjs目录下构建 BokehJS再把构建产物复制到src/bokeh/server/staticinstall跳过构建直接使用bokehjs/build下已有的构建产物其他值抛出ValueError报错。此外setup.py 中Build、EditableWheel、Sdist三个 setuptools 命令在run()时都会先调用check_tags()再执行build_or_install_bokehjs()这解释了为什么缺少 git tag 会导致构建失败。何时需要重新构建 BokehJS每次 BokehJS 源码变化后都必须重新构建 BokehJS——无论是因为你自己改了代码还是从 GitHub 拉取了更新。此时重新运行pip install -e .即可。如果 JavaScript 依赖列表也发生了变化则需要先回到“安装 Node 包”一节重新执行npm ci再重新构建。7. 设置环境变量Bokeh 通过环境变量控制库各部分的运行与交互方式完整清单见 src/bokeh/settings.py 及参考文档中的bokeh.settings。注意只为需要它们的命令或终端会话临时设置不要做成bkdev环境里的永久设置因为不同开发任务需要不同的资源配置运行示例或本地应用、使用本地构建的 BokehJS 时为该命令/会话设置BOKEH_RESOURCES运行测试时保持BOKEH_RESOURCES和BOKEH_DEV不设置——测试套件会自行选择所需资源某些测试在设置了BOKEH_RESOURCES时会在收集阶段失败构建文档时按文档构建说明操作文档构建使用GOOGLE_API_KEY和必要时BOKEH_DOCS_CDN而不是BOKEH_RESOURCES。BOKEH_RESOURCES控制使用哪个版本的 BokehJSBOKEH_RESOURCES是开发 Bokeh 代码库时最重要的环境变量它决定 Bokeh 加载哪个版本的 BokehJS。默认情况下Bokeh 从 CDN 下载所需的 BokehJS JavaScript 代码如果你修改了 BokehJS 代码并在本地构建过就必须让 Bokeh 改用本地版本否则本地改动不会生效。从 src/bokeh/settings.py 的源码可以看出BOKEH_RESOURCES的默认值是cdn而在开发模式BOKEH_DEV下默认值切换为server。合法的模式在 src/bokeh/resources.py 中定义基础模式inline、cdn、server、relative、absolute以及开发模式server-dev、relative-dev、absolute-dev。在运行示例或本地应用、需要加载本地 BokehJS 构建产物时有三种选择方式一absolute-dev—— 从本地安装的 Bokeh 库的 static 目录加载 JavaScript 资源同时使用未压缩的 BokehJS 资源以提高可读性# Linux/macOS export BOKEH_RESOURCESabsolute-dev# Windows (PowerShell) $Env:BOKEH_RESOURCES absolute-dev:: Windows (CMD) set BOKEH_RESOURCESabsolute-dev方式二inline—— 把所有必要的本地 JavaScript 资源直接内联进生成的 HTML 文件中export BOKEH_RESOURCESinline$Env:BOKEH_RESOURCES inlineset BOKEH_RESOURCESinline方式三server-dev—— 通过 Bokeh server 提供本地 BokehJS。先启动本地资源服务器# Linux/macOS BOKEH_DEVtrue bokeh static# Windows (PowerShell) $Env:BOKEH_DEV true bokeh.exe static:: Windows (CMD) set BOKEH_DEVtrue bokeh static然后在新终端窗口中设置BOKEH_RESOURCESserver-devLinux/macOS 用exportWindows PowerShell 用$Env:BOKEH_RESOURCES server-devWindows CMD 用set BOKEH_RESOURCESserver-dev。这种方式额外提供了source maps可以调试原始的 TypeScript 而不是编译后的 JavaScript排查问题更方便。注意BOKEH_RESOURCES只在运行示例或本地应用时设置运行测试或构建文档时不要设置它如已设置则取消否则可能报错。更多细节可参考bokeh.resources.Resources类文档。BOKEH_DEV开发模式快捷开关BOKEH_DEV把本地开发最常用的几项设置合并到一起。在开发示例或应用、或需要为server-dev运行本地资源服务器时使用不要在运行测试套件时开启它因为它隐含了BOKEH_RESOURCESserverexport BOKEH_DEVtrue$Env:BOKEH_DEV trueset BOKEH_DEVtrue从源码看BOKEH_DEV的解析位于 src/bokeh/settings.py 的is_dev()它用convert_bool读取环境变量。设置BOKEH_DEVtrue隐含以下配置但并不严格等价于逐个设置这些变量隐含变量值BOKEH_BROWSERnoneBOKEH_LOG_LEVELdebugBOKEH_MINIFIEDfalseBOKEH_PRETTYtrueBOKEH_PY_LOG_LEVELdebugBOKEH_RESOURCESserver这些默认值在 src/bokeh/settings.py 中都有对应定义例如log_level的 dev_default 为debug、minified的 dev_default 为false、pretty的 dev_default 为true见 L738-L805。这样设置后Bokeh 会使用本地且未压缩的 BokehJS 资源默认日志级别提高生成的 HTML 与 JSON 代码更易读而且每次调用show()时不再弹出新的浏览器窗口。注意BOKEH_DEVtrue启用BOKEH_RESOURCESserver这需要资源服务器配合。如需自行提供可另外运行BOKEH_DEVtrue bokeh staticLinux 下可在另一个终端中执行。虽然使用 server 资源是最稳健的开发方案但也可以简化为把BOKEH_RESOURCES设为inline。关于环境变量的优先级机制从 src/bokeh/settings.py 的PrioritizedSetting类源码可以看到取值顺序立即传入的值 → 用户代码设置的值 → 用户指定配置文件 → 环境变量 → 用户本地配置文件 → 系统级配置文件 → 开发默认值BOKEH_DEV生效时→ 显式默认值 → 全局默认值。这解释了为什么临时环境变量能覆盖全局默认配置。8. 验证本地环境测试 Bokeh 核心安装运行python -m bokeh info输出示例Python version : 3.12.3 | packaged by conda-forge | (main, Apr 15 2024, 18:38:13) [GCC 12.3.0] IPython version : 8.19.0 Tornado version : 6.3.3 NumPy version : 2.0.0 Bokeh version : 3.5.1 BokehJS static path : /opt/anaconda/envs/test/lib/python3.12/site-packages/bokeh/server/static node.js version : v20.12.2 npm version : 10.8.2 jupyter_bokeh version : (not installed) Operating system : Linux-5.15.0-86-generic-x86_64-with-glibc2.35通过该命令可一次性核对 Python 版本、各依赖库版本、Bokeh 版本、BokehJS static 路径、Node.js 与 npm 版本等信息。运行示例接下来运行 Bokeh 自带的独立示例。先把环境变量BOKEH_RESOURCES设为absolute-dev或inline以使用本地 BokehJS然后在 source checkout 目录执行# Linux/macOS BOKEH_RESOURCESinline python examples/basic/data/transform_markers.py# Windows (PowerShell) $Env:BOKEH_RESOURCES inline python.exe .\examples\basic\data\transform_markers.py:: Windows (CMD) set BOKEH_RESOURCESinline python examples\basic\data\transform_markers.py这会在本地生成transform_markers.html文件用浏览器打开即可看到标记变换marker transform可视化效果。对应示例源码位于 examples/basic/data/transform_markers.py。运行 Bokeh Server另一种使用方式是 Bokeh 服务器。设置BOKEH_DEVfalse后在 source checkout 目录运行bokeh serve# Linux/macOS BOKEH_DEVfalse python -m bokeh serve --show examples/server/app/sliders.py# Windows (PowerShell) $Env:BOKEH_DEV False python.exe -m bokeh serve --show .\examples\server\app\sliders.py:: Windows (CMD) set BOKEH_DEVfalse python -m bokeh serve --show examples\server\app\sliders.py--show选项会自动打开浏览器。默认的 Bokeh 服务器地址是localhost:5006。示例中所有滑块都能交互式控制正弦波每次更新都会用新参数重绘曲线。9. 常见问题排查Troubleshooting更新已有开发环境并不总是一帆风顺。通用原则是确保 conda 环境、Node 包和本地构建始终是最新的。以下是文档中列出的常见问题及解决方案Git tags 缺失KeyError: 0.0.1如果仓库的 tags 没有完整克隆到本地构建时可能报KeyError: 0.0.1。检查 tags 是否存在git tag -l | tailWindows 下用git tag -l。如果没有任何 tags请确认已经完成了将 Bokeh 仓库添加为 upstream的步骤。如前文所述setup.py 的check_tags()会因 tags 过少而直接终止构建。Git 提交因行尾符失败test_code_quality.pyFile contains carriage returns在 Windows 系统上推送分支时可能遇到File contains carriage returns at end of line: file path错误。这是因为 Bokeh 只允许 LF 行尾符而某些 Windows 工具会加入 CR LF 行尾符。解决办法git config --global core.autocrlf false执行后删除并重新克隆你的 Fork 仓库。该命令让 git 始终保留原始的 LF 行尾符。从旧版本更新后持续报错如果更新旧环境后不断出错可用conda remove --name bkdev --all删除环境同时删除本地bokeh文件夹然后从本文开头重新搭建开发环境。克隆时网络慢网络慢或超时时可考虑浅克隆shallow clone只下载较少的提交加快克隆速度、减少数据传输量# SSH 方式只克隆最近 1 个提交 git clone --depth 1 gitgithub.com:bokeh/bokeh.git # HTTPS 方式 git clone --depth 1 https://github.com/bokeh/bokeh.git也可以只克隆指定分支的最近提交git clone --depth 1 --branch branch-name --single-branch gitgithub.com:bokeh/bokeh.git浅克隆的局限性包括受限的 Git 操作需要完整历史的操作如某些合并策略、生成完整日志将不可用分支限制未克隆全部分支使用了--single-branch时切换分支可能需要额外步骤版本信息不准确浅克隆时通过bokeh.__version__获取的版本信息可能显示错误数据例如出现dev标签。如需把浅克隆转换为完整克隆可以加深或补全历史# 加深指定数量的提交 git fetch --deepenadditional-commits # 拉取全部历史转为完整克隆 git fetch --unshallow延伸阅读本文对应官方开发者指南原文docs/bokeh/source/docs/dev_guide/setup.rstconda 测试环境文件conda/environment-test-3.12.yml另有 3.13、3.14 等版本见conda目录BokehJS 依赖声明bokehjs/package.jsonpre-commit 钩子配置.pre-commit-config.yaml 及 tools/hooks/install.py、tools/hooks/uninstall.py构建安装逻辑setup.py环境变量定义与优先级src/bokeh/settings.py资源模式实现src/bokeh/resources.py更多安装与运行信息可参阅开发者指南的“additional resources”章节如有疑问欢迎到 Bokeh Discourse 或 Bokeh 贡献者 Slack 提问。【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokeh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考