文章完成标准与维护规则

本系列中的短文首先是待扩写的学习卡片。只有当一篇文章同时讲清问题、机制、取舍和验证方法时，才算完成，而不是以字数或工具数量判断。

推荐结构

一篇完整文章通常包含：

1. 要解决的问题：给出具体场景、失败表现和影响范围。
2. 核心机制：解释浏览器、运行时或工具在内部做了什么。
3. 最小示例：提供可以直接运行的代码、配置和命令。
4. 工程位置：说明它属于开发、构建、测试、交付还是运行阶段。
5. 方案取舍：比较适用条件、迁移成本、生态兼容和退出路径。
6. 常见问题：以“现象 → 证据 → 原因 → 修复”组织排查过程。
7. 实践任务：要求读者主动制造一个失败场景，再完成修复。
8. 验收标准：给出可观察结果，避免“理解了”“配置成功”等模糊结论。
9. 参考资料：优先引用规范、官方文档和项目发布说明。

并非每篇都要机械使用九个标题，但不能缺少问题、机制、取舍和验证四个核心部分。

实践任务怎么写

差的任务：

在最小项目中完成一次 Tree Shaking 验证。

更好的任务：

创建一个导出两个函数的 ESM 模块，只使用其中一个函数；分别在正确和错误声明 sideEffects 时构建项目。使用产物分析工具确认未使用导出是否消失，并记录压缩前后体积。

验收结果应包含：

• 可复现命令
• 输入代码和关键配置
• 成功与失败输出
• 结论及其适用版本

版本规则

工具会变，原理相对稳定。文章应把两者分开书写：

• 原理部分解释依赖图、缓存键、模块解析等长期概念
• 工具部分标明验证过的主版本和日期
• 使用 updatedAt 记录实质更新，而不是覆盖最初发布日期
• 避免“当前最佳”“必须使用”之类没有范围的结论
• 版本变化导致结论失效时，保留迁移背景并链接官方迁移指南

涉及 Vite、TypeScript、浏览器指标和安全策略等快速变化内容时，应至少在主要版本升级后复查一次。

选型表达

不要把工具比较写成固定标签，例如“Webpack 适合应用，Rollup 适合库”。更有价值的比较维度包括：

• 目标运行环境和浏览器范围
• 开发启动、热更新与生产构建模型
• 插件和框架生态
• 模块格式、CSS、静态资源和服务端渲染需求
• 构建规模、缓存和调试能力
• 团队现有经验、迁移成本和维护责任

结论应写成“在这些约束下选择什么”，而不是脱离上下文宣布胜者。

引用与安全

• 优先引用标准组织、浏览器厂商、框架和工具的官方资料
• 示例不能包含真实令牌、内部域名或用户数据
• 安全示例应在隔离环境运行，明确攻击前提与防护边界
• 性能结论必须记录设备、网络、页面版本和测量方式
• AI 生成的代码、结论和引用必须经过运行验证与人工复核

发布前检查

• 标题和描述准确说明文章能解决的问题
• 示例命令可运行，输出与正文一致
• 至少包含一个失败场景和排查过程
• 实践任务具有可观察的验收结果
• 版本相关结论注明版本或更新时间
• 外部链接指向一手资料且仍然有效
• 与前后章节建立必要的内部链接
• 内容完成后再移除 editing: true

返回：前端工程化阅读地图。