曾志威
8f27223fce
Remove fixed machine installation paths, prefer project-local Go and Node toolchains, and resolve build verification and browser test binary paths relative to the project. Add isolated discovery/relocation tests and document compatibility and validation boundaries. Validation: 20 tool-discovery assertions, 3 Node path tests, startup isolation and script syntax checks passed. Frontend build passed; full Go compilation was blocked by unrelated concurrent Kubernetes changes.
3.9 KiB
本地输出目录
程序输出在 bin/；构建缓存使用 bin/build-cache，开发候选程序使用 bin/dev-build，Windows 单 EXE 发布目录使用 bin/releases。开发升级脚本的完整数据备份放在 bin/backups。
bin/backups 包含用户数据，不是可随意删除的编译缓存。旧 artifacts/ 中的测试产物和备份仍保留，不在合并时搬移或清理。验证可使用 artifacts/ 下的独立程序、临时端口和临时数据库，不覆盖运行中的 bin/serviceport.exe。
相对路径与跨机器使用
脚本不保存开发者盘符、用户目录或固定系统安装位置。项目根目录从脚本自身位置推导，与从哪个目录调用无关；复制整个项目到另一台电脑或带空格的其他目录后，不需要改脚本中的路径。
- CMD 入口通过
%~dp0找脚本；PowerShell 通过$PSScriptRoot；Shell 先切换到自身所在项目根目录；Node 通过import.meta.url定位项目。 - 默认输入、输出、缓存和测试二进制都相对项目根目录。
build.ps1 -OutputPath、验证脚本的文件参数及SERVICEPORT_E2E_BINARY的相对值也按项目根目录解释，不按调用者的当前目录。 - 用户主动传入的外部文件路径仍兼容；脚本不会把它们作为跨机器默认值。已有
SERVICEPORT_DATA自定义数据库路径和 AppData 兼容逻辑不改动。 - 运行时仍会把路径规范化用于启动进程、校验删除范围和防止递归备份。这些是动态计算的路径，不是写死在脚本中的绝对路径。Docker fixture 的容器内挂载点和入口路径属于容器契约，不是宿主机器路径，不随本次修改改变。
Windows 构建工具查找
源码中的 start-dev.cmd 每次先准备当前源码对应的程序，因此仍需 Go、Node.js 和 npm；缓存不会免除开发工具依赖。只运行软件时，使用预编译发行版的 serviceport.exe，无需安装这些工具。
可以把对应操作系统与架构的完整工具链放进项目：
serviceport/
tools/
go/bin/go.exe
node/node.exe
node/npm.cmd
node/node_modules/npm/...
scripts/
start-dev.cmd
上面只列关键文件；Go 和 Node 均需复制完整发行目录，不是只复制 EXE。tools/go、tools/node 不进入 Git 或 Docker 构建上下文。复制项目到另一台电脑时，如果需要便携构建，应自行一起复制这些工具目录；git clone 不会下载工具链。
Windows 查找顺序为：
- 可选
SERVICEPORT_GO/SERVICEPORT_NODE，建议使用项目相对路径；显式路径无效时直接报错，不偷偷降级。 - 项目内
tools/go/bin/go.exe、tools/node/node.exe，优先于机器 PATH。 - 当前机器 PATH 中的对应应用程序，不再扫描 Program Files、AppData、用户目录或 SDK 安装位置。
Node 便携目录必须包含配套 npm。选定的 Node/npm 目录只在构建子进程的 PATH 中优先，不修改系统 PATH；直接使用 Node 执行 build-web.mjs 时也优先使用该 Node 目录中的 npm。Linux/macOS Shell 入口同样优先使用 tools/go/bin、tools/node/bin，没有则使用 PATH，工具需是对应系统版本。
默认工具目录齐全时直接双击 start-dev.cmd，无需设置路径。自定义相对位置示例：
$env:SERVICEPORT_GO = 'tools/go/bin/go.exe'
$env:SERVICEPORT_NODE = 'tools/node/node.exe'
.\start-dev.cmd -BuildOnly
-BuildOnly 只构建候选程序，不启动、不停止或替换现有服务，也不迁移真实数据库。构建脚本固定 GOTOOLCHAIN=go1.25.0；本次不自动下载、安装或打包编译器，已有 Go 的工具链获取仍由 Go 自身及网络配置决定。工具缺失时在服务停机和处理数据之前失败，并提示放入项目工具目录或配置 PATH。安装工具或修改用户 PATH 后需重新打开终端。
验证记录见 测试记录。