人生进阶指南如何以 navigation.mjs 为唯一来源用 npm run sync 同步 SUMMARY 与英文词表镜像【免费下载链接】upAn advanced guide which might benefit you a lot . 韩先凯的人生进阶指南 人生进阶指南 离谱的人生 人生进阶 离谱的英语学习指南/英语学习教程/英语学习/学英语项目地址: https://gitcode.com/GitHub_Trending/en/up在维护《人生进阶指南》up 仓库时只要改动了中英导航结构或中文词表根目录的SUMMARY.md、docs/en/threads/word-list/下的英文镜像页等生成文件就会和源头脱节。CI 会拒绝未同步的生成文件进入主分支所以手动改这些文件是走不通的。本文的任务是修改源头文件后用npm run sync重新生成 SUMMARY 与英文词表镜像并验证所有生成文件与源头一致。适用前提是已在 Node.js 24 环境下克隆了仓库版本约束见.nvmrc、.node-version和 package.json 中的engines要求24 25。哪些文件是源头哪些文件是生成物按 MAINTENANCE.md 与 CONTRIBUTING.md 的说明源头与生成物的对应关系是docs/.vitepress/navigation.mjs 是中英文导航的唯一来源。它驱动三个生成文件根目录SUMMARY.md、docs/SUMMARY.md、docs/en/SUMMARY.md。docs/threads/word-list/下的中文词表是词表的维护来源docs/en/threads/word-list/下的英文页是生成物页内自带注释Generated by scripts/sync-word-lists.mjs; edit docs/threads/word-list instead.。docs/README.md是源头根目录README.md是按仓库相对路径重写的镜像。docs/assets/feature.svg与feature-en.svg会被复制到docs/public/assets/作为 VitePress 分享图。触发同步的时机在 CONTRIBUTING.md 中写得很明确改动导航、中文首页或中文词表之后运行npm run sync。新增章节同样要先更新navigation.mjs和双语页面再走同步见 MAINTENANCE.md 的“书稿结构”一节。准备环境首次拿到仓库时按 MAINTENANCE.md 的“环境与命令”一节操作nvm use # 切到 Node 24版本约束见 .nvmrc / .node-version / package.json npm ci # 从 lock file 精确安装依赖npm ci安装的是 package.jsondevDependencies中的 VitePress、Playwright、markdownlint-cli2、sharp 等npm run sync本身只依赖 Node 内置模块但保持依赖完整可以让后续npm run check直接可用。改动源头navigation.mjs 的条目结构在运行同步之前先确认你在 docs/.vitepress/navigation.mjs 里的改法符合校验规则。该文件导出zhNavigation与enNavigation两个分组数组每条页面用page(text, link, source)生成const page (text, link, source ${link.replace(/^\//, )}.md) ({ text, link, source, });同步脚本 scripts/sync-navigation.mjs 在生成前会做两类检查写错会在npm run check:navigation阶段直接抛错退出字段与链接检查每个条目必须同时有text、link、source同一 locale 内不允许重复linksource解析到docs/下必须真实存在。报错文案分别是导航条目字段不完整、导航存在重复链接: link、导航 source 不存在: source。双向覆盖检查docs/下所有公开 Markdown排除.vitepress、public、assets与SUMMARY.md必须都出现在导航里反之导航source也不能指向不公开的 Markdown。新页面没进导航会报公开 Markdown 未被导航收录: source这正是 MAINTENANCE.md 所说的“避免新页面成为孤岛”的实现。新增页面时source缺省按link推导去掉前导/后加.md页面文件名与路由不一致时才需要显式传第三个参数例如归档页page(归档说明, /threads/archive/, threads/archive/README.md)。运行 npm run syncnpm run sync在 package.json 中定义为按顺序执行四个脚本node scripts/sync-navigation.mjs node scripts/sync-word-lists.mjs node scripts/sync-public-assets.mjs node scripts/sync-readme.mjs各步骤的职责依据脚本源码scripts/sync-navigation.mjs完成上文的两类导航检查再生成根目录SUMMARY.md链接带docs/前缀、docs/SUMMARY.md和docs/en/SUMMARY.md英文链接会去掉en/前缀。scripts/sync-word-lists.mjs遍历docs/threads/word-list/下每个.md先把中文源页归一化重写 frontmattertitle: 标题 词表、固定updated: 2026-08-16并截取到“本页是查阅清单”提示段为止再据此生成docs/en/threads/word-list/下同名英文页。scripts/sync-public-assets.mjs把feature.svg、feature-en.svg复制到docs/public/assets/。scripts/sync-readme.mjs把docs/README.md改写为仓库根README.md其中站内链接统一补上docs/前缀。执行命令npm run sync输出的判读方式每个发生变化的文件会打印updated 文件路径例如updated SUMMARY.md、updated docs/en/threads/word-list/Python.md完全没有变化时对应脚本打印navigation summaries are in sync、English word lists are in sync、public social images are in sync或README mirror is in sync。四个脚本全部无变化说明生成文件已经和源头一致。注意第 2 步会写回中文词表源文件本身归一化其 frontmatter 与尾部提示段所以即使你只改了导航git status里也可能出现词表目录下的变更这属于脚本的正常行为。验证同步结果同步后的验证分两层都来自 MAINTENANCE.md 与脚本的--check模式看 diffnpm run sync之后检查生成文件差异再提交。git diff应只包含你预期变化的 SUMMARY、英文词表、README 镜像或分享图如果 diff 出现意料之外的文件先回头核对navigation.mjs是否漏改或改错。跑只读校验npm run check会依次执行check:navigation三个脚本带--check参数、check:readme、check:content、check:format。只读模式不会写文件发现不一致时打印错误并以非零码退出典型输出如SUMMARY.md: 导航文件未同步 docs/en/threads/word-list/Python.md: 英文词表未同步 README.md: 未与 docs/README.md 同步运行 npm run sync看到这类输出说明某处生成文件落后于源头重新运行npm run sync后再校验即可。最终的兜底是 CIMAINTENANCE.md 写明 CI 会再次生成这些文件并阻止未提交的差异进入主分支CONTRIBUTING.md 的表述是CI rejects unsynchronised generated files.。本地npm run check通过等价于把 CI 的这道门禁提前跑了一遍。同步完成后的发布顺序当这次改动涉及新增或大幅改写页面时MAINTENANCE.md 的“章节发布门禁”给出了完整命令序列npm run sync只是第一步npm run sync npm run check npm run docs:build npm run test:smoke最后一步的 Playwright 烟测会从导航source自动生成中英文页面覆盖因此导航条目没配好时问题会在烟测阶段暴露而不是静默漏页。测试产生的test-results/与playwright-report/是失败诊断文件不属于书稿内容测试失败清理后重跑npm run check即可。边界与限制navigation.mjs的“唯一来源”只针对导航与三份 SUMMARY英文词表的唯一维护来源是docs/threads/word-list/不要反向编辑英文镜像它会在下次npm run sync时被覆盖。词表脚本对中文源页做的是归一化frontmatter 会被重写、正文截取到“本页是查阅清单”提示段该提示段内容由脚本统一生成并附指向词汇篇../part-1/2-vocabulary.md的固定引导语。想把词表页改成其他版式改脚本而不是改生成产物。批量入口npm run check包含内容校验与 markdownlint本文场景只需要其中的check:navigation/check:readme来验证同步但若改动是页面级别的发布按上面的四步序列走完更符合仓库门禁要求。迁移前的 Docsify 旧站保留在 Git 历史提交42e6faa与本同步流程无关仅在站点路径或索引故障的回滚场景中才需要见 MAINTENANCE.md “回滚”一节。【免费下载链接】upAn advanced guide which might benefit you a lot . 韩先凯的人生进阶指南 人生进阶指南 离谱的人生 人生进阶 离谱的英语学习指南/英语学习教程/英语学习/学英语项目地址: https://gitcode.com/GitHub_Trending/en/up创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
人生进阶指南如何以 navigation.mjs 为唯一来源用 npm run sync 同步 SUMMARY 与英文词表镜像
人生进阶指南如何以 navigation.mjs 为唯一来源用 npm run sync 同步 SUMMARY 与英文词表镜像【免费下载链接】upAn advanced guide which might benefit you a lot . 韩先凯的人生进阶指南 人生进阶指南 离谱的人生 人生进阶 离谱的英语学习指南/英语学习教程/英语学习/学英语项目地址: https://gitcode.com/GitHub_Trending/en/up在维护《人生进阶指南》up 仓库时只要改动了中英导航结构或中文词表根目录的SUMMARY.md、docs/en/threads/word-list/下的英文镜像页等生成文件就会和源头脱节。CI 会拒绝未同步的生成文件进入主分支所以手动改这些文件是走不通的。本文的任务是修改源头文件后用npm run sync重新生成 SUMMARY 与英文词表镜像并验证所有生成文件与源头一致。适用前提是已在 Node.js 24 环境下克隆了仓库版本约束见.nvmrc、.node-version和 package.json 中的engines要求24 25。哪些文件是源头哪些文件是生成物按 MAINTENANCE.md 与 CONTRIBUTING.md 的说明源头与生成物的对应关系是docs/.vitepress/navigation.mjs 是中英文导航的唯一来源。它驱动三个生成文件根目录SUMMARY.md、docs/SUMMARY.md、docs/en/SUMMARY.md。docs/threads/word-list/下的中文词表是词表的维护来源docs/en/threads/word-list/下的英文页是生成物页内自带注释Generated by scripts/sync-word-lists.mjs; edit docs/threads/word-list instead.。docs/README.md是源头根目录README.md是按仓库相对路径重写的镜像。docs/assets/feature.svg与feature-en.svg会被复制到docs/public/assets/作为 VitePress 分享图。触发同步的时机在 CONTRIBUTING.md 中写得很明确改动导航、中文首页或中文词表之后运行npm run sync。新增章节同样要先更新navigation.mjs和双语页面再走同步见 MAINTENANCE.md 的“书稿结构”一节。准备环境首次拿到仓库时按 MAINTENANCE.md 的“环境与命令”一节操作nvm use # 切到 Node 24版本约束见 .nvmrc / .node-version / package.json npm ci # 从 lock file 精确安装依赖npm ci安装的是 package.jsondevDependencies中的 VitePress、Playwright、markdownlint-cli2、sharp 等npm run sync本身只依赖 Node 内置模块但保持依赖完整可以让后续npm run check直接可用。改动源头navigation.mjs 的条目结构在运行同步之前先确认你在 docs/.vitepress/navigation.mjs 里的改法符合校验规则。该文件导出zhNavigation与enNavigation两个分组数组每条页面用page(text, link, source)生成const page (text, link, source ${link.replace(/^\//, )}.md) ({ text, link, source, });同步脚本 scripts/sync-navigation.mjs 在生成前会做两类检查写错会在npm run check:navigation阶段直接抛错退出字段与链接检查每个条目必须同时有text、link、source同一 locale 内不允许重复linksource解析到docs/下必须真实存在。报错文案分别是导航条目字段不完整、导航存在重复链接: link、导航 source 不存在: source。双向覆盖检查docs/下所有公开 Markdown排除.vitepress、public、assets与SUMMARY.md必须都出现在导航里反之导航source也不能指向不公开的 Markdown。新页面没进导航会报公开 Markdown 未被导航收录: source这正是 MAINTENANCE.md 所说的“避免新页面成为孤岛”的实现。新增页面时source缺省按link推导去掉前导/后加.md页面文件名与路由不一致时才需要显式传第三个参数例如归档页page(归档说明, /threads/archive/, threads/archive/README.md)。运行 npm run syncnpm run sync在 package.json 中定义为按顺序执行四个脚本node scripts/sync-navigation.mjs node scripts/sync-word-lists.mjs node scripts/sync-public-assets.mjs node scripts/sync-readme.mjs各步骤的职责依据脚本源码scripts/sync-navigation.mjs完成上文的两类导航检查再生成根目录SUMMARY.md链接带docs/前缀、docs/SUMMARY.md和docs/en/SUMMARY.md英文链接会去掉en/前缀。scripts/sync-word-lists.mjs遍历docs/threads/word-list/下每个.md先把中文源页归一化重写 frontmattertitle: 标题 词表、固定updated: 2026-08-16并截取到“本页是查阅清单”提示段为止再据此生成docs/en/threads/word-list/下同名英文页。scripts/sync-public-assets.mjs把feature.svg、feature-en.svg复制到docs/public/assets/。scripts/sync-readme.mjs把docs/README.md改写为仓库根README.md其中站内链接统一补上docs/前缀。执行命令npm run sync输出的判读方式每个发生变化的文件会打印updated 文件路径例如updated SUMMARY.md、updated docs/en/threads/word-list/Python.md完全没有变化时对应脚本打印navigation summaries are in sync、English word lists are in sync、public social images are in sync或README mirror is in sync。四个脚本全部无变化说明生成文件已经和源头一致。注意第 2 步会写回中文词表源文件本身归一化其 frontmatter 与尾部提示段所以即使你只改了导航git status里也可能出现词表目录下的变更这属于脚本的正常行为。验证同步结果同步后的验证分两层都来自 MAINTENANCE.md 与脚本的--check模式看 diffnpm run sync之后检查生成文件差异再提交。git diff应只包含你预期变化的 SUMMARY、英文词表、README 镜像或分享图如果 diff 出现意料之外的文件先回头核对navigation.mjs是否漏改或改错。跑只读校验npm run check会依次执行check:navigation三个脚本带--check参数、check:readme、check:content、check:format。只读模式不会写文件发现不一致时打印错误并以非零码退出典型输出如SUMMARY.md: 导航文件未同步 docs/en/threads/word-list/Python.md: 英文词表未同步 README.md: 未与 docs/README.md 同步运行 npm run sync看到这类输出说明某处生成文件落后于源头重新运行npm run sync后再校验即可。最终的兜底是 CIMAINTENANCE.md 写明 CI 会再次生成这些文件并阻止未提交的差异进入主分支CONTRIBUTING.md 的表述是CI rejects unsynchronised generated files.。本地npm run check通过等价于把 CI 的这道门禁提前跑了一遍。同步完成后的发布顺序当这次改动涉及新增或大幅改写页面时MAINTENANCE.md 的“章节发布门禁”给出了完整命令序列npm run sync只是第一步npm run sync npm run check npm run docs:build npm run test:smoke最后一步的 Playwright 烟测会从导航source自动生成中英文页面覆盖因此导航条目没配好时问题会在烟测阶段暴露而不是静默漏页。测试产生的test-results/与playwright-report/是失败诊断文件不属于书稿内容测试失败清理后重跑npm run check即可。边界与限制navigation.mjs的“唯一来源”只针对导航与三份 SUMMARY英文词表的唯一维护来源是docs/threads/word-list/不要反向编辑英文镜像它会在下次npm run sync时被覆盖。词表脚本对中文源页做的是归一化frontmatter 会被重写、正文截取到“本页是查阅清单”提示段该提示段内容由脚本统一生成并附指向词汇篇../part-1/2-vocabulary.md的固定引导语。想把词表页改成其他版式改脚本而不是改生成产物。批量入口npm run check包含内容校验与 markdownlint本文场景只需要其中的check:navigation/check:readme来验证同步但若改动是页面级别的发布按上面的四步序列走完更符合仓库门禁要求。迁移前的 Docsify 旧站保留在 Git 历史提交42e6faa与本同步流程无关仅在站点路径或索引故障的回滚场景中才需要见 MAINTENANCE.md “回滚”一节。【免费下载链接】upAn advanced guide which might benefit you a lot . 韩先凯的人生进阶指南 人生进阶指南 离谱的人生 人生进阶 离谱的英语学习指南/英语学习教程/英语学习/学英语项目地址: https://gitcode.com/GitHub_Trending/en/up创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
