yuxuanhui
91861565bb
- Introduced API guidelines for interface contracts and request handling. - Added design tokens usage guidelines for consistent styling across the project. - Established DTO guidelines for defining request parameters and response data types. - Created frontend structure guidelines to clarify directory organization and code placement rules. - Compiled a comprehensive frontend development guideline document covering various aspects of the development process. - Implemented quality guidelines to ensure code maintainability and adherence to best practices.
76 lines
4.2 KiB
Markdown
76 lines
4.2 KiB
Markdown
---
|
||
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.
|