“在我机器上能跑”是架构问题

人们熟悉的说法是：软件在开发人员工作站上运行正常，却在其他地方失败，这常被视为调试中的老生常谈。实际上，它描述的是一种架构缺陷：系统的一部分行为存在于版本控制之外。源代码可能完全相同，但实际执行环境在运行时版本、CPU 架构、文件系统语义、区域设置、时区、原生库、证书、环境变量、依赖解析或构建工具方面存在差异。当这些输入仍然隐含时，开发人员工作站就成了一种未记录在案的依赖。由此产生的失败不只是环境上的不便，而是证明系统缺乏对其预期构建和运行条件的完整、可复现定义。可复现构建实践基于同一原则：已声明的源码和构建输入应创建一条通往生成产物的可独立验证路径，而不是依赖隐藏的机器状态。

机器本身就是一种输入，即使仓库假装并非如此

代码仓库通常会捕获应用源代码、配置模板和依赖清单，但运行假设往往仍留在仓库之外。使用一个 JDK 编译的服务在另一个 JDK 下可能表现不同。依赖主机时区的代码会继承机器配置，而 Java 的默认时区源自 JVM 运行所在的环境；因此，获取系统默认值的 API 在不同主机上可能返回不同值。区域设置（Locale）也有类似特性，因为 JVM 会维护一个默认区域设置，它可能影响对区域设置敏感的操作。

更安全的做法是在应用程序边界处显式声明重要的默认值。例如，用于交换的时间戳不应静默继承工作站配置：

String timestamp = eventTime
    .atZone(ZoneOffset.UTC)
    .format(DateTimeFormatter.ISO_OFFSET_DATE_TIME);

使用显式的 UTC 偏移量可将主机时区从此操作中移除。同样的原则适用于数字解析、字符编码、路径、排序和区域格式化。只有当机器恰好共享这些默认值时，默认值才方便。当环境选择被表示为已声明的输入或显式不变式时，架构会变得更可预测。Java 的时间 API 区分瞬时时间、偏移量和完整时区规则（包括夏令时的间隙和重叠），因此只要本地时间参与应用逻辑，这种区分就很重要。

文件系统行为会造成一种更微妙的偏差。Git 记录了 core.ignoreCase，因为包括 APFS、HFS+、FAT 和 NTFS 在内的文件系统可能要求以不区分大小写的方式处理。Git 在创建或克隆仓库时会探测此行为，并据此配置其操作。因此，对 Config.json 的引用在一个环境中可能看似有效，但部署会失败，因为仓库中实际包含的是 config.json。

可复现性始于部署之前

锁定应用依赖是必要的，但并不充分。包管理器、编译器、操作系统库、运行时和构建期工具也参与产物的生成。例如，npm 的 npm ci 要求存在锁文件，并且当 package.json 与锁文件不一致时会退出，而不是修改锁文件来适应当前安装。这种行为使依赖解析更适合自动化、可重复的构建。

node --version
npm --version
npm ci
npm test

当 Node.js 和 npm 版本由 CI 控制，而不是继承自碰巧安装的版本时，这些命令会变得有意义得多。一次成功的工作站构建不应定义正确性；从已声明输入执行的一次干净构建才应定义正确性。密封构建系统更进一步。Bazel 将密封操作定义为：消费已声明的输入，而不是主机文件系统中的任意文件，并产生已声明的输出。沙箱有助于检测对本地工具或文件的意外依赖。其架构收益不止于缓存和构建速度，因为未声明的依赖可以变成构建失败，而不是一直隐藏到另一台机器缺少它时才暴露。这改变了一种重要关系：

source + declared dependencies + declared toolchain
↓
artifact

工作站不应成为该等式中额外的隐形操作数。

容器减少机器漂移，但并不能消除它

容器很有用，因为它们打包了一个受控的用户空间，但容器化并不能让主机差异消失。CPU 架构仍然很重要。Docker 将 linux/amd64 和 linux/arm64 视为不同的平台目标，并提供多平台构建，以生成跨操作系统和架构组合的镜像。原生库、JNI 依赖、编译后的 Node 模块以及架构特定的可执行文件会立即暴露这些差异。CI 流水线可以将架构支持变成可执行的要求：

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --tag registry.example.com/payments:${GIT_SHA} \
  --push .

这比部署后才发现架构不匹配更强，因为受支持的平台成为构建契约的一部分。基础镜像引入了另一个环境变化的来源。容器标签是可能随时间指向更新镜像内容的引用。当精确的镜像身份很重要时，Docker 建议固定摘要，因为引用摘要可确保即使关联标签之后发生变化，也会选择同一镜像版本。

ARG RUNTIME_IMAGE
FROM ${RUNTIME_IMAGE}
ENV TZ=UTC
COPY service.jar /app/service.jar
ENTRYPOINT ["java", "-Duser.timezone=UTC", "-jar", "/app/service.jar"]

流水线可以将 RUNTIME_IMAGE 提供为已批准的仓库加上不可变摘要。基础镜像更新随后成为显式变更，可以经过构建、测试、审查和部署，而不是因为浮动标签移动而出现。因此，容器缩小了环境边界，但并没有消除定义它的要求。

开发环境应纳入版本控制

开发机器不需要复现生产环境的每一个运行细节，但决定软件行为的工具链应当是可描述的。开发容器规范（Development Container Specification）的存在，是为了将开发专用工具、设置、运行时配置和元数据捕获到如 devcontainer.json 这样的机器可读定义中。

{
  "name": "payments-service",
  "image": "ghcr.io/example/java-dev@sha256:",
  "containerEnv": {
    "TZ": "UTC",
    "LANG": "en_US.UTF-8"
  }
}

重要的并不是这一特定格式。架构目标是：一台干净的机器能够重建所需工具链，而不依赖手动安装的编译器、凭记忆保留的 shell 配置、过时的全局包或未记录的 IDE 状态。这一区别将文档与可复现性区分开来。安装指南描述的是预期会产生某个环境的操作。可执行的环境定义则直接参与生成该环境。后者更容易持续验证，也明显更难以被误解。

环境假设应当可观测

即使是受控环境也可能发生漂移。当启动时记录运行时身份以及应用版本和构建提交，生产诊断会变得更容易。Java 直接暴露运行时、架构、时区和区域设置信息，从而可以捕获相关执行特征，而无需暴露任意环境变量。

log.info(
    "runtime java={} arch={} timezone={} locale={} commit={}",
    Runtime.version(),
    System.getProperty("os.arch"),
    ZoneId.systemDefault().getId(),
    Locale.getDefault().toLanguageTag(),
    buildCommit
);

这种指纹将环境比较转化为证据。仅在 aarch64 上、特定时区下或不同运行时版本下发生的缺陷，可以与实际执行元数据相关联，而不是与事故讨论中口头传递的机器描述相关联。关键假设可以进一步成为启动不变式：

if (!ZoneId.systemDefault().equals(ZoneOffset.UTC)) {
    throw new IllegalStateException(
        "Unsupported runtime timezone: " + ZoneId.systemDefault()
    );
}

立即失败通常比让不受支持的环境产生细微错误的状态更安全。测试也应遵循同样的原则。软件有意支持的维度应在 CI 中变化，而必须保持不变的维度应被冻结。跨平台构建验证 CPU 目标。干净包安装验证依赖锁。区分大小写的环境会暴露路径错误。显式时区测试会揭示对主机默认值的意外依赖。这种区分是架构性的：受支持的变异性会被测试，不受支持的变异性会被移除。

架构必须定义机器边界

针对环境特定故障的持久解决方案，不是更庞大的安装文档或更长的故障排查清单。而是对系统输入进行更严格的定义，其中包括锁定的依赖、受控的工具链、固定的基础镜像、显式的区域设置和时区行为、经过验证的 CPU 架构、在可行时采用密封构建、可复现的开发环境，以及可观测的运行时身份。Reproducible Builds 将可复现性描述为从源码到二进制文件的可独立验证路径，而同样的工程纪律可以扩展到该二进制文件执行所在的环境。因此，可靠的软件架构不仅仅包括源代码、服务、数据库和部署拓扑。它还包括将代码与机器连接起来的假设。当这些假设被声明、版本化、测试并可观测时，环境特定故障就会变成具有可追踪原因的一般工程缺陷。当它们仍然隐含时，每一台工作站都会悄然变成一种不同的架构。DZone 贡献者表达的观点仅代表他们自己。