前端工程化首批：锁文件、测试、构建与静态验收

Node/npm/Vite 的安装、测试、构建和 Chromium 产物检查沿用原文 2026-10-17 历史批次；本轮未重跑。下文命令用于核对锁文件、脚本、dist 与预览之间的关系。

前置：Node运行时与模块、JavaScript/HTML/CSS，以及至少能运行一个React项目或Vue项目。工程化按依赖、脚本、产物与诊断组织，不把它当另一套框架API。目标是能解释并复现从源码到可验证静态产物的路径，不在本批引入发布账号或本站业务后端。

环境、包管理与工作目录

本批工具链Node24.21.0、npm11.19.0、Vite8.3.4，Windows amd64实际安装构建，Chromium验证产物。Vite8要求Node20.19+或22.12+等受支持范围；本项目固定兼容的24.x，不以更换全局Node解决任意依赖冲突。macOS不纳入本轮验收。

先运行node --version、npm --version并读当前目录package.json。本站根package.json与教学应用各自独立，不在根目录给所有项目混装依赖。每个应用保留自己的锁文件；不要把全局vite或另一个项目的node_modules当成可复现条件。

依赖、锁文件与scripts

package.json声明直接依赖与脚本；package-lock还记录实际解析的版本、依赖树及完整性信息。npm ci要求锁与清单一致，按锁重建node_modules；修改依赖后应通过相应安装命令有意识更新锁，再看差异。不把“删除锁文件再试”当常规修复，因为它可能改变整棵依赖树。

运行依赖和开发依赖是部署/安装约定，不表示开发依赖永远不执行代码。安装脚本也有影响，应使用可信来源；本批仅安装固定教学依赖。包审计报告需按路径和实际受影响版本判断，不为了清零数字盲目执行可能破坏兼容的大版本修复。没有外部包的Node CLI无需npm install。

脚本会在包目录下执行，并把本地node_modules/.bin放入命令路径。npm run preview -- --port 5190中独立分隔符--后面的--port 5190传给Vite；它不是写入应用代码的参数。失败进程应非零退出，后续CI或Shell才有可靠判断依据。

转换、类型检查与测试

Vite开发服务器为模块提供转换和更新能力；生产构建创建部署资产；tsc做完整静态类型检查；模型测试检查所覆盖业务行为。四者不能互相替代。JS版框架示例没有tsc脚本，不虚构“build已经检查所有TS类型”；独立TypeScript项目的npm test明确先tsc再运行测试。

React/Vue应用把纯模型与界面分开，因此Node可测规则，但不会挂载真实DOM。完整验收另需浏览器检查表单、key/事件、焦点、文本转义、窄屏及刷新行为。运行一次模型测试不能证明所有组件可用；构建成功也不能证明没有运行时错误。

完整构建与静态预览路径

本工作包复用两份已经给出全部文件的真实应用，不额外造一套演示目录。配置分别见React完整源码、Vue完整源码，锁文件在examples/web-plus/react与vue中。选择一个项目目录运行：

npm ci
npm test
npm run build
npm run preview -- --port 5190

Vue可选5191避免端口冲突。每步成功后再执行下一步，失败先读输出，不继续用旧dist冒充新构建。npm ci按锁安装；test预期两组通过；build生成dist/index.html与assets文件；preview输出本机地址。打开后完成添加、完成、筛选、删除、刷新为空，输入HTML样式文本只显示文字。

两个项目都提供npm run verify，它用npm test && npm run build在测试失败时停止构建。源码包含的vite.config.mjs选择对应框架插件和base:'./'；生产index中资源地址应与部署位置相容。构建文件的哈希名会随内容/工具版本变化，不把某个固定哈希当永久预期。

TypeScript项目另运行npm ci、npm test、npm run demo，验证类型与运行边界；故意TS2322文件在fixtures，不加入正式include。添加真实CI前，先让这些命令在本地有明确结果。本批不上传产物或配置外部发布凭据。

base、环境变量与静态资源

站点放在子路径时，资源URL必须按部署位置解析；base用于构建资源前缀，./让本例无路由静态页面的产物使用相对资产。它不自动处理任意客户端路由、深层URL或服务端回退规则；引入Router后要另行设计history与部署。

Vite客户端可见的环境值会被打入前端产物，不能放密钥或把它当服务端授权。静态dist中没有安全存储凭据的角落。public中的文件通常原样复制，源码import的资源由工具处理；缓存/CDN、source map发布和内容哈希策略需要结合实际部署环境，本批只验证本机静态服务。

常见失败与验收表

• npm ci提示清单/锁不一致：核对有意修改的依赖，用对应npm版本更新并审阅锁，别直接忽略失败。
• EBADENGINE：核对实际Node路径和包要求；安装了新版本但终端仍用旧路径并未完成切换。
• 预览仍是旧代码：先重新build，确认所服务的dist和端口；开发服务的更新不等于生产资产重建。
• 页面空白或资源404：检查Network中的实际模块/资产URL、base和响应Content-Type，而非反复改组件业务逻辑。
• 类型检查成功但数据错误：检查unknown输入的运行校验，TS类型已擦除，浏览器不会据此拒绝坏JSON。

本批真实检查React/Vue生产页的核心操作、空白拒绝、安全文本和390px；可访问性更深审计、跨浏览器矩阵与正式服务器部署不冒称完成。

练习与参考解法

1. 修改App文字后只刷新preview，预测为什么可能不变。2. 在临时副本中让测试失败，运行verify观察构建是否仍执行。3. 把产物放到子目录静态服务，核对相对资产；不要由此推断任意路由都成功。4. 解释运行类型包、tsc、Vite转换与浏览器权限之间的区别。

提示与参考解法

preview服务现有dist，需要重建；verify中的&&在非零测试退出时短路。临时副本验证完恢复测试，不修改正式期望来凑通过。无路由页面相对资产可随目录移动，history路由还需服务器规则。类型声明只帮助静态检查，不添加fs、process或跨源权限；运行能力来自实际宿主与已实现代码。真正的发布还需环境、回滚、缓存与监控方案，本批不默默添加。

依据：Vite指南、官方中文指南、生产构建、环境变量、npm ci、npm scripts。核对2026-10-17。

深入课程已接续：多入口和完整验证矩阵。基础内容与旧锚点保留，按当前路线进入完整机制和实践。