Codex升级依赖实操：markdown-it版本迁移、回归与回退

用markdown-it 14.3.0到15.0.2的教学迁移，检查变更日志、固定锁文件，发现自动链接行为变化并补配置，最后演示限定范围回退。

2026-07-28约 5 分钟阅读Codex使用教程

先看重点：快速结论

用已明确发布的两个版本演示，版本号不是对所有项目的升级建议。
裸域名自动链接回归能被测试捕获，恢复既有行为需显式配置。

本文目录 · 跳到当前步骤

本例把一个独立 Markdown 渲染练习从 markdown-it 14.3.0 升到 15.0.2，用裸域名自动链接的变化演示如何发现回归。它不是要求真实项目安装旧版本或无条件升到这个版本；实际选型先检查当前发布与安全信息。

建立可恢复的小项目

在新的 dependency-demo 目录操作，使用 Node.js 20+、npm 与 Git。不要在正在开发的主项目里执行下面的初始化。保存 package.json：

json

{
  "name":"dependency-demo",
  "private":true,
  "type":"module",
  "scripts":{"test":"node --test render.test.mjs"},
  "dependencies":{"markdown-it":"14.3.0"}
}

保存 render.mjs：

import MarkdownIt from 'markdown-it';
const md = new MarkdownIt({ html: false, linkify: true });
export const render = source => md.render(source);

保存 render.test.mjs：

import test from 'node:test';
import assert from 'node:assert/strict';
import { render } from './render.mjs';
test('标题仍被渲染', () => {
  assert.equal(render('# 标题'), '<h1>标题</h1>\n');
});
test('显式 HTTPS 链接保持', () => {
  assert.match(render('https://example.com'), /href="https:\/\/example.com"/);
});
test('既有产品契约：裸域名也自动链接', () => {
  assert.match(render('www.example.com'), /href="http:\/\/www.example.com"/);
});
test('禁用原始 HTML', () => {
  assert.match(render('<script>alert(1)</script>'), /&lt;script&gt;/);
});

在此目录安装并运行：

powershell

npm install --ignore-scripts
npm test
npm ls markdown-it
node --version

先记录真实输出。基线失败时先解决原因，不要把旧失败算到升级头上。安装会产生 package-lock.json；本例没有需要运行的安装脚本，使用 --ignore-scripts。真实项目可能依赖构建钩子，不能不核对就照搬这个选项。

确认基线后，提交三个源文件和锁文件到这个独立练习仓库，并建立 markdown-baseline 标签。若已有仓库和标签，使用自己的明确检查点，不强制覆盖。

powershell

git init
git add -- package.json package-lock.json render.mjs render.test.mjs
git commit -m "Save markdown rendering baseline"
git tag markdown-baseline

让 Codex 先读版本差异

官方变更日志中，15.0.0 调整了 linkify-it 的默认行为，裸链接推断不再默认开启；还移除了 markdown-it/lib/* 等内部子路径导出。15.0.2 又包含解析性能问题的修复。除了版本数字，还要搜索项目是否用了这些被改动的行为或内部接口。

text

只读当前依赖、锁文件、render.mjs 和测试。
阅读 markdown-it 从14.3.0到15.0.2的官方变更日志。
先列与本项目有关的变化、需要新增或保留的回归，以及暂时不用处理的无关功能。
不要升级其他依赖，不要把 npm install 成功当作完成。

本例只用公开入口，没有内部子路径；裸域名自动链接却是明确的产品契约，所以需要保留那条测试。项目没有承诺这个行为时，可以选择接受新默认，但需同步需求与测试，不能为了变绿删除失败断言。

升级后应先观察失败

powershell

npm install --save-exact --ignore-scripts [email protected]
npm test
git diff -- package.json package-lock.json

教学预期：裸域名测试暴露差异，其余已有行为仍按断言检查。不要先让 Codex 自动修改所有快照。

本例决定保留原行为，因此在 render.mjs 创建 md 后增加一行：

md.linkify.set({ fuzzyLink: true });

再运行 npm test、npm ls markdown-it，并检查依赖和锁文件差异是否只包含该包及必要传递依赖。四个断言通过也只覆盖这四项；真实站点还需验证自身插件、frontmatter、输出 HTML 与业务页面。

失败时限定范围回退

先保存失败改动的 diff 或提交，确认没有其他人的修改。若决定恢复这个练习的基线：

powershell

git restore --source=markdown-baseline --worktree -- package.json package-lock.json render.mjs
npm ci --ignore-scripts
npm test

这会覆盖列出的三个工作区文件，不能在混合未保存工作中直接使用。npm ci 按锁文件安装并重建依赖目录；不要只改 package.json 而留着另一个版本的锁文件或 node_modules。

最终记录目标版本、变更理由、命中的回归、实际命令结果、未覆盖插件和恢复点。没有执行目标版本测试时，应明确写“方案已准备、迁移未验证”。

资料来源

markdown-it 官方变更日志
2026-10-11 核对 15.0.0 自动链接默认变化、内部子路径移除和 15.0.2 修复。
npm ci
按已有锁文件安装；教程禁止顺带升级全项目。

下一步

继续阅读与你当前问题相关的教程：