浏览 AI使用教程

操作教程怎样写环境、步骤、预期结果和失败排查

操作教程不能只写命令。环境版本、执行位置、预期输出和常见报错要放在对应步骤旁边,读者才知道自己做对了还是已经偏了。

需要哪一项,就直接查到哪一段

把表格、命令、清单或规则作为工作中的查询工具,不要求从头顺序阅读。

教学示例

一句“安装依赖并运行”,为什么别人照做还是报错

一句“安装依赖并运行”漏掉工作目录、文件内容和成功表现,读者遇到错误后只能猜。本例用只有一个 server.mjs 的本地首页,把缺的步骤补出来。

这是单文件教学程序;文末分别说明本机执行结果和未做的浏览器检查。

  • node --version 与执行目录已记录
  • 首页请求返回 200 且含指定 H1
  • 不存在路径返回 404
字段参考

技术教程结构与验收清单要写清哪些字段

要记录的内容怎么填写检查点
环境和版本系统、软件、账号、权限、目录和文档核验日期。读者知道是否适用
安全起点备份、测试环境、工作区状态和不可逆动作确认。失败可以恢复
操作步骤每步写动作、位置或命令、预期结果和下一步条件。不靠作者现场解释
必要示例当格式、公式、代码或判断是教学对象时给完整可运行例子。文件完整;实际执行与预期结果分别标注
排错与验收只写症状、根因、修复和复测,最终结果有截图、输出或检查。读者能定位失败并证明成功
怎样处理

同一个例子先写清执行环境

以下命令在 Windows PowerShell 中运行。使用 Node.js 24,先执行 node --version 记录实际补丁版本;若显示找不到 node,先安装 Node 并新开终端确认 PATH,不能跳过。

可复制练习

新建空目录并进入

教学输入

新建空目录并进入

New-Item -ItemType Directory -Path .\tutorial-local-demo
Set-Location -LiteralPath .\tutorial-local-demo
Get-Location
node --version

如果目录已经存在,另选一个新名称,避免覆盖已有文件。目录应是后续保存 server.mjs 的位置。

可复制练习

用编辑器新建 server.mjs,保存为 UTF-8

教学输入

用编辑器新建 server.mjs,保存为 UTF-8

import { createServer } from 'node:http';
const port = Number(process.env.PORT || 4173);
const html = '<!doctype html><html lang="zh-CN"><meta charset="utf-8"><title>本地练习</title><h1>本地教程已启动</h1><p>这是教学首页。</p></html>';
const server = createServer((req, res) => {
  if (req.url !== '/') {
    res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
    res.end('Not found');
    return;
  }
  res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
  res.end(html);
});
server.on('error', (error) => {
  console.error(error.code || error.message);
  process.exitCode = 1;
});
server.listen(port, '127.0.0.1', () => console.log('Local: http://127.0.0.1:' + port));

这是完整文件。无需 npm install。

可复制练习

在包含 server.mjs 的目录启动

教学输入

在包含 server.mjs 的目录启动

node .\server.mjs

预期终端打印 Local: http://127.0.0.1:4173 并保持运行;不是打印后立即退出。

可复制练习

在第二个 PowerShell 窗口检查首页

教学输入

在第二个 PowerShell 窗口检查首页

$response = Invoke-WebRequest -Uri http://127.0.0.1:4173/ -UseBasicParsing
$response.StatusCode
$response.Content.Contains("<h1>本地教程已启动</h1>")

预期依次为 200 和 True。再在浏览器打开相同地址,检查页面 H1 是否可见;终端结果不能替代浏览器目视检查。

教学示例

按具体症状定位,再用同一个 URL 复测

现象先查什么处理与复测
MODULE_NOT_FOUNDGet-Location 与 Get-ChildItem 是否能看到 server.mjs进入正确目录;检查是否误存成 server.mjs.txt,再启动
EADDRINUSE4173 已被另一进程占用不要盲目杀进程。在当前终端设 $env:PORT = "4174" 后重启,检查 URL 同步改为 4174
返回 404请求是否为 /,而非 /index.html本例只有 / 路由;访问 /missing 应得到 404
浏览器连接被拒绝服务终端是否已退出修复终端错误并重启;完成后 Ctrl+C 停止服务,连接停止是预期行为
怎样处理

这份代码实际检查到了哪里

2026-10-11 在 Windows、Node.js v24.15.0 运行同一 server.mjs:4173 端口占用时返回 EADDRINUSE;改用 PORT=4174 后首页 HTTP 200,响应含指定 H1,/missing 返回 404。再次启动同端口进程时退出码为 1,并输出 EADDRINUSE。

这些记录来自本机命令与 HTTP 响应检查。没有执行手机或桌面浏览器目视检查,也没有安装 Vite、连接外部 API 或发布网站;读者仍应在浏览器检查自己的首页。

本例材料

这份技术教程结构与验收清单服务哪项任务

需要确认本例内容
现有材料Windows PowerShell;已安装 Node.js 24;一个新建空目录;下方完整 server.mjs。程序只用 Node 内置模块,不需要 npm 包、账号或 API Key。
不能越过的边界此页演示技术教程的写法;代码只监听本机地址。记录真实版本和运行结果,未做的浏览器/设备检查必须保留待检查。
要交付的结果技术教程结构与验收清单
本例交付

完成后的技术教程结构与验收清单

读者最终得到 server.mjs、一条本机 URL,以及首页 200、标题文本、错误路径 404、端口冲突的核对记录。文中预期输出用于与自己机器的实际结果对照。

常见失败

为什么“命令在作者电脑通过,读者仍无法复现”还不能交付

命令在作者电脑通过,读者仍无法复现

原因
遗漏隐含环境、已有全局依赖或当前目录
怎么改
用干净环境重走并记录每个前置条件,删掉未验证的捷径
验收方式

技术教程结构与验收清单通过哪些检查才算完成

依据与范围

本页实际使用的资料