---
id: 20260627-cloud-runtime-project-root
title: 云端运行时不要依赖 process.cwd() 推断项目根目录
created: 2026-06-27
updated: 2026-06-27
status: candidate
scope: global
category: debugging
confidence: high
last_verified: 2026-06-27
promotion_target: none
projects:
  - evaluator-agent
tags:
  - cloud-deployment
  - path-resolution
  - playwright
  - diagnostics
---

# 云端运行时不要依赖 process.cwd() 推断项目根目录

## Trigger

本地测试能读到配置或资源，但部署到云端后同一流程表现为配置缺失、鉴权未执行、文件不存在、资源路径 404，且日志里只看到后续业务失败。

## Context

一次 Playwright 云端测试排查中，测试进程能访问目标页面，但前置鉴权没有执行，页面最终停留在登录页。最初怀疑是 cookie/sessionStorage 写入失败、Chrome 限制或跨域问题。后来通过运行时证据确认：fixture 已经执行，但没有读到项目 auth 配置。

关键差异是云端 Playwright 进程的 `process.cwd()` 是应用包目录，而项目文件和 `.evaluator/projects/<id>.json` 在另一个工作目录。代码用 `process.cwd()` 推断项目根目录，导致读取了错误位置的配置文件。

## Evidence

- 2026-06-26/27，`evaluator-agent` 云端测试排查。
- 运行时 `auth-setup` 证据显示：`projectIdPresent=true`，但 `authConfigured=false`，`authApplied=false`。
- 临时深度诊断曾显示运行时尝试读取 `/app/.evaluator/projects/<project-id>.json`，但实际项目产物位于 `/workspace/project/...`。
- 修复提交：`ee1e9b0 Fix Playwright project root resolution for auth config`。
- 相关文件：
  - `packages/core/src/evaluator/run.ts`：启动 Playwright 时传入 `EVALUATOR_PROJECT_ROOT=projectRoot`。
  - `packages/playwright/src/fixtures/ai-test.ts`：fixture 读取配置时使用 `EVALUATOR_PROJECT_ROOT || process.cwd()`。
  - `.trellis/spec/frontend/run-analysis-contracts.md`：记录云端 cwd 与项目根目录可能不同的契约。
- 清理提交：`8547bd1 chore: remove temporary auth debug diagnostics`，保留稳定布尔证据，删除过细路径/配置探测字段。

## Root cause

已验证原因：云端运行进程的 cwd 不等于项目根目录。配置读取逻辑把 `process.cwd()` 当作项目根，导致读取错误路径，表现为配置不存在。

推断：类似问题也可能发生在测试报告、静态资源、项目级配置、凭证文件、生成产物、fixture 初始化、CLI 子进程中，只要代码通过 cwd 隐式推导项目根。

## Preferred action

对需要部署到云端或由子进程执行的代码：

1. 显式传递项目根目录，例如 `PROJECT_ROOT` / `EVALUATOR_PROJECT_ROOT`，而不是在下游模块里直接信任 `process.cwd()`。
2. 子进程启动处负责设置这个 env；fixture、worker、CLI helper 只读取显式根目录并保留 `process.cwd()` 作为本地直跑 fallback。
3. 在运行产物里记录低风险、结构化的健康检查字段，例如 `projectIdPresent`、`authConfigured`、`authApplied`，用于远程确认流程是否执行。
4. 临时深度诊断可以短期记录路径、config existence 等字段定位问题，但修复后应清理，避免长期暴露内部部署结构。
5. 把这个约束写成项目契约或测试，防止以后又退回 cwd 推断。

## Boundaries

- 本地单进程脚本、一次性维护脚本、明确从仓库根执行的工具可以使用 `process.cwd()`，但要把这个前提写清楚。
- 不要把密码、token、cookie 值、请求 body/header 值写入诊断产物。
- 路径诊断是否保留要看用户场景：短期排查可以详细，长期产品化证据应收敛到必要布尔状态和可操作错误摘要。

## Failed approaches

- 先排查 cookie/sessionStorage、CORS、Chrome flags 和页面 JS 错误，虽然有价值，但没有直接回答“fixture 是否读到配置”。
- 临时把 `configPath`、`configFilePresent`、`projectRoot` 等字段加入运行时证据能快速定位问题，但不适合作为长期默认产物。
- 不推荐把配置复制到云端 cwd 对应目录；这会形成两份配置，后续 UI、测试和服务端可能读到不同来源。

## Promotion record

- Not promoted.