50 lines
6.3 KiB
Markdown
50 lines
6.3 KiB
Markdown
# 2026-08-18
|
||
|
||
## article 组件改为 SSR（按需服务端渲染）
|
||
|
||
- 目标：`src/components/pages/article.astro` 由「浏览器 Alpine fetch 取数（CSR）」改为「服务端渲染 + 灯箱保留 Alpine」。
|
||
- 组件改动：接收 `article: RawArticle | null` 作为 prop，服务端直出标题/品牌/日期/图片网格/正文段落（利于 SEO 与首屏，无 loading 骨架）；图片地址服务端补全绝对路径；灯箱仍是 Alpine 客户端交互，但图片数据由服务端以 `x-data={articleView(${JSON.stringify(images)})}` 注入。`locale` 控制文案（en/cn），`error` 控制服务端错误态（missing/failed）。
|
||
- 页面改动：`pages/article.astro`、`pages/cn/article.astro`、`pages/en/article.astro` 三页均加 `export const prerender = false`，frontmatter 按 `Astro.url.searchParams.get('id')` 调 `fetchArticleById(id, API)` 取数后传给组件。`API = import.meta.env.API_SSR || PUBLIC_API_BASE || http://localhost:8090`。
|
||
- `src/lib/data.ts`：`fetchArticleById(id, apiBase=API_BASE)` 增加 `apiBase` 参数（复用 brands 的 API_SSR 内部地址模式）；`RawArticle` 类型补 `created_at?: number`（组件引用了它）。
|
||
- 验证：`npm run build` 通过（exit 0），article 不再生成静态 html，作为 3 个按需 chunk 进 `dist/server/`；dev 下 `/en/article?id=1`、`/cn/article?id=2` 返回 200，HTML 里可见服务端渲染的错误态文案「加载文章失败，请刷新或稍后再试」与 `articleView([])` 注入（后端离线时 article=null），证明 SSR 生效、不再是浏览器 fetch。
|
||
|
||
## 重要更正：astro.config.mjs 的 prefixDefaultLocale 实际为 true
|
||
- 08-16 记忆误记为 `false`；当前 `astro.config.mjs` 实为 `prefixDefaultLocale: true`（routing.prefixDefaultLocale）。
|
||
- 因此**无前缀路由全部 404**：`/article`、`/shows`、`/articles` 都 404，只有 `/en/...`、`/cn/...` 可用。
|
||
- 这导致既存的内部链接（`shows.astro`/`articles.astro`/`Index.astro` 里的 `/article?id=`）点过去是 404——属**既存全局 i18n 路由问题**，非本次 SSR 改动引入（这些无前缀路由在我改之前就 404）。
|
||
- **部署缺口**：当前 `nginx.conf` 只做静态托管 + `/api` 反代；article 现在是按需 SSR 路由，线上需 Node 服务承接，nginx 必须把 `/en/article`、`/cn/article` 等 SSR 路由代理到 Node 服务，否则线上 404。
|
||
|
||
## 修复 swiper TS2307「找不到模块"swiper"或其相应的类型声明」
|
||
- 现象：VS Code 报 `ts(2307)` 找不到模块 `swiper`，但 `package.json` 的 `dependencies` 里已声明 `swiper: "^11.2.10"`。
|
||
- 根因：`node_modules/swiper` **根本不存在**——依赖写进了 package.json 却没真正 install 进 node_modules（疑似此前 `npm install` 未执行 / node_modules 被裁剪）。所以 TS 服务找不到模块与类型声明。
|
||
- 修复：`npm install swiper@^11.2.10`（落盘后 `node_modules/swiper` 完整，版本 11.2.10；`exports` 映射正常：`.`→swiper.mjs/swiper.d.ts，`./modules`→types/modules/index.d.ts，`./css`→swiper.css，`./css/navigation`、`/free-mode`→对应 css）。Index.astro 的 5 行 import 全部可解析。
|
||
- 提醒：若 VS Code 仍报红，执行「TypeScript: Restart TS Server」（Ctrl+Shift+P）或重开文件即可，因 TS 服务可能缓存了旧缺失状态。
|
||
|
||
## 修正：article 面包屑应复用现有 Breadcrumb 组件（非手写）
|
||
- **更正**：上一节「article 组件加面包屑」我手写了 `<nav>` 面包屑并自加 `home/archive/brand` 字典键，属于重复造轮子。用户指出项目已有 `src/components/Breadcrumb.astro`（shows 页在用）。
|
||
- **正确做法**：article.astro 改用 `<Breadcrumb items={crumbs}><span slot="current">{title}</span></Breadcrumb>`。组件约定：
|
||
- `items[].label` 是 **i18n 英文 key**（组件内部 `t()` 翻译），不要预先 `t()`；末项用 `<slot name="current">`。
|
||
- `Home` / `Runway Archive` 已在 `dictionary.ts` 有 cn 翻译（首页/走秀档案）。
|
||
- 品牌名作为动态 label 传入 `t()` 会回退原文（dict 无此 key），即显示品牌名本身。
|
||
- 语言跟随 `Astro.currentLocale`，href 需调用方自己给 locale 前缀（en→`/en/shows`，cn→`/cn/shows`，首页 en→`/en/` cn→`/cn`）。
|
||
- 撤掉手写的 `lbl.home/archive/brand`；`src/lib/data.ts` 的 `brand_id` 字段保留（品牌面包屑链接用）。
|
||
|
||
## article 组件加面包屑（Breadcrumb）
|
||
- 位置：`src/components/pages/article.astro` 顶部，把原来「返回首页 + Runway·品牌」那一行（border-b 顶栏）整体替换为标准面包屑 `<nav aria-label="Breadcrumb">`：`首页 / 走秀档案 / 品牌名 / 文章标题`。
|
||
- 链接层级（均按 locale 给前缀，避免 404）：
|
||
- 首页 `homeHref`：`/en/`（en）或 `/cn`（cn）。
|
||
- 走秀档案 `archiveHref`：`/en/shows` 或 `/cn/shows`（实测两路由均 200，是可用的全局走秀档案页）。
|
||
- 品牌 `brandHref`：`archiveHref + "?brand_id=<id>"`（当 `article.brand_id` 存在，指向品牌筛选后的走秀档案）；否则退化为 archiveHref。
|
||
- 当前文章标题：末级、不可点、`truncate` 防溢出。
|
||
- 文案（en/cn）新增 `home`(Home/首页)、`archive`(Runway/走秀档案)、`brand`(Brand/品牌兜底) 三个 key，沿用既有 mono 小字号大写编辑风。
|
||
- `src/lib/data.ts`：`RawArticle` 类型新增 `brand_id?: number`（后端 `/api/public/articles/:id` 返回此字段），供品牌面包屑筛选链接使用。
|
||
- 验证：`npm run build` 通过；`astro dev` 下 `/en/article?id=1` 返回 200，无运行时错误。面包屑本体在 `article ?` 分支，需后端在线有数据时才可见。
|
||
|
||
## 项目小坑（PowerShell / Node）
|
||
- `package.json` 含 `"type": "module"`，因此临时 `.js` 脚本被当 ESM，`require` 不可用；需用 `.cjs` 后缀或用 `import`。
|
||
- PowerShell 里 `||` 会被当成管道、多路径 `dir a b` 报错；做 node 自检时优先写 `.cjs` 脚本文件再 `node` 执行。
|
||
|
||
## 待用户决策（未动，留给用户定）
|
||
1. 是否修复内部 `/article?id=` 链接为 locale 前缀版（如 `/en/article?id=` / `/cn/article?id=`，按当前页 locale 生成）。需改 shows.astro / articles.astro / Index.astro 等。
|
||
2. 是否更新 nginx.conf + Dockerfile/docker-compose 让 Node SSR 服务承接 article 路由。
|