浏览 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_FOUND | Get-Location 与 Get-ChildItem 是否能看到 server.mjs | 进入正确目录;检查是否误存成 server.mjs.txt,再启动 |
| EADDRINUSE | 4173 已被另一进程占用 | 不要盲目杀进程。在当前终端设 $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、端口冲突的核对记录。文中预期输出用于与自己机器的实际结果对照。
为什么“命令在作者电脑通过,读者仍无法复现”还不能交付
命令在作者电脑通过,读者仍无法复现
- 原因
- 遗漏隐含环境、已有全局依赖或当前目录
- 怎么改
- 用干净环境重走并记录每个前置条件,删掉未验证的捷径
