跳转到主要内容

本地开发指南

本地开发指南

英文版本 为准，本文供参考。本指南长期维护通用环境设置、开发与验证操作；每次变更另有 .local/acceptance/ 下仅中文、不提交的临时清单，持久结果保留在该变更的公开日志。

1. 进入功能 worktree

以下命令针对 macOS / zsh，以四版方案 worktree 为例；后续变更按开发流程 使用自己的目录与分支。从标准 main/ 目录进入：

git worktree add -b feat/new-feature-name ../new-feature-name main
cd ../new-feature-name
git branch --show-current

预期分支为 feat/new-feature-name。后续命令都在这个包含 package.json 的目录执行，功能改动在同级 worktree 开展；也可用同样的环境设置在 main 本地查看已认可版本。

2. 首次安装固定版本环境

安装或切换工具前，先记录 node --version、pnpm --version 和 go version；命令不存在时记为“未安装”。保留旧版本以便恢复；升级已有环境时，先阅读该变更日志及本地清单中的迁移评估。

工具要求版本用途
Node.js26.8.2Astro、脚本及测试
pnpm12.4.1项目依赖和命令
Go1.27.1解析 OINK Hugo 模块
Hugo Extended0.166.0构建/启动日志站；在第 3 步安装

**Node.js：**如果已使用 nvm，在当前终端执行以下命令。每个新终端都要运行 nvm use 26.8.2；版本文件本身不会自动切换 Node。

nvm install 26.8.2
nvm use 26.8.2
node --version

如果 nvm 已安装但未加载，运行 . "${NVM_DIR:-$HOME/.nvm}/nvm.sh"。没有版本管理器时，从 Node.js 26.8.2 发布页 下载安装 macOS .pkg，重开终端并确认输出 v26.8.2。已有 nvm 的用法见官方说明 。

**pnpm：**将精确版本安装到用户自己的目录，并把命令目录加入当前终端 PATH：

npm install --global --prefix "$HOME/.local" pnpm@12.4.1
export PATH="$HOME/.local/bin:$PATH"
pnpm --version

预期输出 12.4.1。希望新终端自动可用时，把相同的 export PATH 行添加一次到 shell 配置。这里 npm 仅用于安装 pnpm；项目依赖和命令全部使用 pnpm。官方包 也固定了对应平台二进制的版本。

**Go：**先运行 go version；如果已显示 go1.27.1，跳过安装。否则在 Go 1.27.1 下载页 选择对应 macOS 安装包：Apple Silicon 使用 darwin-arm64.pkg，Intel 使用 darwin-amd64.pkg。按官方安装步骤 安装，重开终端并确认版本。uname -m 可查看架构：arm64 或 x86_64。

3. 安装项目依赖

pnpm install --frozen-lockfile
pnpm tools:hugo
.cache/hugo/hugo version

第一条按现有锁文件安装；第二条下载并校验 Hugo Extended 0.166.0，放入已忽略的 .cache/hugo/。版本输出须含 v0.166.0 和 +extended。Astro、TypeScript、Wrangler 都是已锁定的项目依赖，不需要单独安装。首次启动/构建日志站还会通过 Go 下载 OINK。

本地浏览不需要 .env、Cloudflare 账号、token 或域名。.env.example 仅说明可选 canonical URL；生产设置另行进行。安装时需要能够访问官方包/发布地址及 Go 模块服务。

4. 启动、检查和停止两站

终端 A：进入功能根目录，启用固定的 Node/pnpm 环境后运行：

pnpm dev --host 127.0.0.1 --port 4321

打开 http://127.0.0.1:4321/，中文入口为 /zh/。终端 B：进入同一个功能根目录，启用相同环境，然后运行：

pnpm dev:logs

打开 http://127.0.0.1:4322/，中文入口为 /zh/。这是两个独立的开发服务器，会监听文件修改；保持终端打开。分别在各自终端按 Ctrl+C 停止对应服务。 若端口被占用，先停掉之前的服务，再重试；以命令实际打印的 URL 为准。

可复用的手动检查：

  • 个人站：查看首页、项目列表、项目详情和经历；在项目页切换 EN/ZH，确认进入对应项目。没有 Research tab、比较页或演示页面。
  • 布局/可访问性：检查窄屏，使用 Tab 和跳转正文链接，启用系统/浏览器的减少动态效果偏好；确认内容可读、焦点可见、页面没有横向溢出。
  • 日志站：打开变更文章、README 和指南；切换语言、点击文档链接，并分别用文章中存在的英文/中文词语搜索。
  • 内容编辑：按内容指南 临时新增一对 EN/ZH Markdown，应无需改组件即可显示；检查后移除临时条目。草稿/发布验证和生产 404 在第 5 步检查。

5. 自动检查与生产产物预览

pnpm verify 执行完整测试。浏览器检查直接读取两站静态产物，包括 OINK 搜索，不监听端口，也不需要启动开发服务。

pnpm exec playwright install chromium
pnpm verify
pnpm deploy:dry-run

Playwright 浏览器只需在首次配置或浏览器版本升级时下载。Linux CI 使用 pnpm exec playwright install --with-deps chromium。

预期：类型检查、单元测试、两站静态构建、产物测试、桌面/移动端浏览器测试及真实内容构建夹具通过。夹具证明新增双语内容生成路由、草稿不输出、缺少译文/不安全 slug 使真实构建失败。浏览器覆盖语言目标、键盘焦点、减少动效、布局、404 和中英文 OINK 搜索。两份 Wrangler dry run 均应成功且不上传；dry run 不需要登录 Cloudflare。

如需手动检查构建结果，在 pnpm verify 后分别于两个终端运行：

node scripts/serve-static.mjs dist/portfolio 4310
node scripts/serve-static.mjs dist/logs 4311

打开 http://127.0.0.1:4310/ 和 http://127.0.0.1:4311/。个人站 /not-a-page/ 应返回 HTTP 404，并提供 EN/ZH 返回链接。生产预览只展示上次构建产物，修改后须重新构建。各自在终端按 Ctrl+C 停止。这些本地服务器是验收工具；部署后的静态页面不需要 Node 应用服务器。

6. 常见问题与交付边界

  • 版本/engine 不匹配：运行 node --version、pnpm --version、go version 和 command -v node pnpm go；修正版本选择/PATH，不要放宽版本检查或重新生成锁文件。
  • 找不到 Hugo：运行 pnpm tools:hugo。若下载需要使用受信任的系统证书，可尝试 NODE_USE_SYSTEM_CA=1 pnpm tools:hugo；不要关闭 TLS 验证。
  • 缺少浏览器：运行 pnpm exec playwright install chromium。手动预览端口被占用时，先停止对应的旧预览进程。

核对预期源码/配置/文档/锁文件、双语含义、精确版本及隐私。生成产物、缓存、.env 和浏览器 trace 保持忽略。每次变更的本地清单、持久验收/迁移证据、所选审查及提交确认按开发流程 执行。

GitHub 必需检查/PR 规则、生产凭据、Cloudflare 上传/路由/DNS 和线上 URL，仍须获准的部署设置 后验证；本地验收不代表线上行为通过。