本机离线资源库

本项目的统一资源库默认位于：

/home/mes123456/resource-library/web-freecad-bitbybit

可通过 WEB_FREECAD_RESOURCE_LIBRARY 或各命令的 --library=PATH 改为其他位置。资源库不进入项目 Git；仓库保存资源定义，资源库自己的 manifest.json 保存每个归档和镜像的字节数、文件数、SHA-256、上游提交及工作树状态。

资源范围

config/offline-resources.json 固定以下资源：

Node 22.23.2 原始发行包、两个 package-lock.json 对应的最小 npm 内容缓存，以及当前项目 node_modules 快照；
FreeCAD 1.1.1（含 GSL、OndselSolver、AddonManager、测试子模块）、bitbybit、OCCT 8、OpenCAMLib、CAMotics/C! 和 LinuxCNC Web 工作树；
FreeCAD headless/desktop Oracle、FreeCAD sysroot、OCCT/PlaneGCS 原生 Worker 制品和可选增量构建目录；
Playwright Chromium/Firefox/WebKit、Boost/Eigen 头文件，以及本机 /var/cache/apt/archives 中的 Debian 安装包池。
QtBase 6.8.2 源码、静态 wasm Qt6Core SDK 与可选增量构建缓存；源码包使用 Qt 官方 SHA-256 校验，国内 USTC 镜像仅作为传输源。

LinuxCNC 和 CAMotics 存在尚未合入各自上游提交的本地适配，因此保存完整工作树快照。working_ocl/ 是上述源码的历史重复副本，不作为规范资源；构建入口实际使用的 OpenCAMLib/、CAMotics/ 和 .cache/bitbybit/bitbybit 才进入资源库。

OCCT 增量构建缓存固定恢复到 .cache/bitbybit/occt-history-build-offline，其 CMake 缓存引用项目内 .cache/occt/occt，不包含旧工作区的绝对源码路径。

同步与校验

./npmw run offline:inventory
./npmw run offline:sync
./npmw run offline:check
./npmw run offline:smoke

offline:sync 只读取现有本机资源，不从互联网下载。首次同步会压缩数 GB 的源码和构建缓存；后续在上游提交、本地适配、工具链或 lockfile 变化后重新执行。

offline:check 逐项重新计算 SHA-256。offline:smoke 先在临时空目录用资源库 npm 缓存执行 npm ci --offline，再运行运行时/FreeCAD 源码/原生 Worker 检查和生产构建。npm 的 --offline 为强制模式，缺包时直接失败，不会访问 registry。资源库保持只读；离线 shell 按 manifest 哈希把 npm 内容初始化到项目 .cache/offline-npm，npm 的访问索引只写入这份工作缓存。

从资源库恢复

恢复操作必须显式限定资源，且默认拒绝覆盖现有目录：

./npmw run offline:restore -- --only=project-node-modules,freecad-source,occt-source

确认目标可替换后使用：

./npmw run offline:restore -- --only=project-node-modules --force

也可验证到独立临时工作目录：

target_dir="$(mktemp -d)"
./npmw run offline:restore -- --target="$target_dir" --only=freecad-source

不要对工作区根目录使用递归删除；恢复工具会检查每个目标必须位于指定 --target 下。

离线开发环境

以下命令启动一个明确禁止 npm 网络回退的 shell：

./scripts/offline-shell.sh

也可以直接运行单条命令：

./scripts/offline-shell.sh ./npmw run dev
./scripts/offline-shell.sh ./npmw run build
./scripts/offline-shell.sh ./npmw run ci:real -- --lane=wasm

环境中会设置 npm_config_offline=true、PLAYWRIGHT_BROWSERS_PATH、FIREFOX_BIN、WEBKIT_BIN、FREECAD_SOURCE_OFFLINE=1、项目内 OCCT_SOURCE_DIR 和固定 Chrome 路径。Firefox/WebKit 使用 manifest 中实际归档的可执行 revision，不要求它恰好等于当前 Playwright 包的默认下载 revision。Node bootstrap 在项目 .runtime/downloads 缺少发行包时也会先查资源库；设置 WEB_FREECAD_OFFLINE=1 后若资源库仍缺包，会直接失败而不调用 curl。

系统包恢复边界

源码、npm、Node、浏览器缓存和项目制品可以直接恢复到普通用户目录。CMake、Ninja、Emscripten、Chrome、Firefox、Qt、V8 和 FreeCAD 原生依赖属于 Debian 系统包；资源库保留了本机 apt 包池，并生成标准 Packages/Packages.gz 索引。安装系统包仍需要管理员权限。例如先把两个本地目录登记成仅本机 apt 源：

printf '%s\n' \
  'deb [trusted=yes] file:/home/mes123456/resource-library/web-freecad-bitbybit/system/debian13-amd64/packages ./' \
  'deb [trusted=yes] file:/home/mes123456/resource-library/web-freecad-bitbybit/system/debian13-amd64/freecad-packages ./' \
  | sudo tee /etc/apt/sources.list.d/web-freecad-offline.list
sudo apt-get update -o Dir::Etc::sourcelist=/etc/apt/sources.list.d/web-freecad-offline.list -o Dir::Etc::sourceparts=-
sudo apt-get --no-download install emscripten cmake ninja-build

这一步只在系统工具被卸载或重装主机时需要。日常断网开发直接使用当前已安装工具链。

4.9 KiB Raw Blame History Unescape Escape