Skip to content

fix: 修复 hatchling readme 路径越界导致的后端构建失败 + dev.sh bash 3.2 兼容 - #180

Open
len0day wants to merge 2 commits into
shy3130:mainfrom
len0day:fix/dev-startup
Open

fix: 修复 hatchling readme 路径越界导致的后端构建失败 + dev.sh bash 3.2 兼容#180
len0day wants to merge 2 commits into
shy3130:mainfrom
len0day:fix/dev-startup

Conversation

@len0day

@len0day len0day commented Aug 16, 2026

Copy link
Copy Markdown

问题与复现

在新版 hatchling 下执行 uv sync(或任何需要构建 backend 包的操作)直接失败:

ValueError: Readme path must be within the project directory:
../README.md

另外在 macOS 自带 bash 3.2 下运行 ./dev.sh,当 BACKEND_EXTRAS 为空时因 set -u 下空数组 ${#ARR[@]} 展开报 unbound variable 直接退出。

根因

  1. pyproject.tomlreadme = "../README.md" 指向项目目录之外,新版 hatchling 的 metadata 校验(metadata/core.pyreadme 属性校验)明确禁止该情况。
  2. dev.shset -euo pipefail 下用 ${#BACKEND_EXTRA_ARGS[@]} 判断 extras,bash 3.2 对空数组做 # 展开仍视为 unbound,bash 4.x 行为不同。
  3. 顺带发现:feat(search): 标的搜索支持拼音首字母 + 创业/科创/北交所徽标 #151 合并后 uv.lock 未同步(lock 中后端版本仍是 0.1.83、缺少 pypinyin),与 pyproject 不一致。

解决方案

  • backend/README.md 新增软链接指向根 READMEpyproject.toml 的 readme 改为 "README.md":根 README 仍是唯一内容来源,不产生两份拷贝。
  • dev.sh 改用 ${#BACKEND_EXTRA_ARGS[@]:-0} 兜底,兼容 bash 3.2/4.x。
  • uv.lock 同步为当前 pyproject 的解析结果(补 pypinyin 0.55.0,后端版本 0.1.83 → 0.1.88,registry 保持清华源不变)。

兼容性

  • 软链接在 git 中以 mode 120000 存储;Windows 上若未开启 symlink 支持,会检出为含链接路径的普通文件——build 仍能成功,仅 wheel 元数据描述不准确,不影响本地 editable 安装与运行。
  • uv.lock 同步后 uv sync --locked 不再与 pyproject 冲突;清华源 URL 保持原样。
  • 不涉及任何运行时业务逻辑、数据契约、缓存或 API 变化。

性能

纯构建/启动脚本修复,不进入任何运行时热路径。

验证结果

  • 删除 .venvuv sync 成功安装全部 122 个包(macOS arm64 / Python 3.12.12)。
  • ./dev.sh 在本机 bash 3.2 下前后端均正常启动:backend :3018 OpenAPI 200、frontend :3011 200;应用启动日志显示 18 条策略加载、enriched 缓存计算完成、matrix cache 预热成功。
  • git diff --check 通过。

界面证据

无界面变化,不适用。

风险与回滚

  • 剩余风险:Windows 检出软链为文本文件的极端场景仅影响 wheel 元数据(见兼容性);未在其他 Linux 发行版 / Python 3.11 环境实测。
  • 回滚方式:revert 本 PR 即可恢复原状,无数据或配置迁移。

新版 hatchling 校验要求 readme 必须位于项目目录内,readme = "../README.md"
导致 uv sync 构建 editable 包时直接失败。改为在 backend/ 下放置指向根
README 的软链,pyproject 的 readme 指向 "README.md",根 README 仍是唯一
内容来源。

uv.lock 同步为当前 pyproject 的解析结果:补上 shy3130#151 合并后缺失的
pypinyin 0.55.0,并把 lock 中后端版本从 0.1.83 更新到 0.1.88。

已验证:删除 .venv 后 uv sync 成功,uvicorn 正常启动,应用加载完成。
macOS 自带 bash 3.2 在 set -u 下展开空数组 ${#ARR[@]} 会报 unbound
variable,导致 BACKEND_EXTRAS 为空时启动直接失败。改用
${#BACKEND_EXTRA_ARGS[@]:-0} 兜底。

已验证:本机 bash 3.2 下 ./dev.sh 前后端均正常启动。
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants