> For the complete documentation index, see [llms.txt](https://docs.zongsoft.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zongsoft.com/get-started/run-and-debug.md).

# 运行与调试

按进程、插件、配置、服务和业务调用逐层定位运行问题。

调试应针对实际运行目录。源码已修改、项目已编译和宿主已经加载新版本是三件事；先确认进程路径及最终 DLL，再分析业务行为。

## 从最小可观察结果开始

完成 [Discussions 部署](/get-started/deploy-first-plugin.md)后，先检查 Web 宿主启动和两个业务清单加载，再使用 discussions/docs/http/forum.http 中的论坛只读请求。确认运行目录中的 DLL/PDB 与本地构建一致。

Web 场景先检查监听地址和 `/Application`，随后验证 Discussions 的[业务控制器](/framework/web/controllers.md)。连接不上时不要先排查控制器；404 时也不要先修改数据库。

## 分层排障

| 层次   | 核对内容              | 常见原因                     |
| ---- | ----------------- | ------------------------ |
| 进程   | 入口路径、运行时、退出日志     | 启动了错误 DLL、运行时缺失          |
| 插件   | 扫描目录、清单与依赖        | 只复制 DLL、依赖名称不一致          |
| 配置   | 文件基名、环境、host/site | 修改了未匹配的选项文件              |
| 服务   | 注册契约、别名、模块/提供者    | Resolve/Find/Locate 用法混淆 |
| 首次调用 | 外部地址、权限、依赖 DLL    | 延迟连接失败、传递依赖覆盖            |
| 业务结果 | 数据、事务、确认与状态       | 查询形状、幂等或权限范围不符           |

## 断点与符号

附加调试器到实际宿主进程，确保 DLL、PDB 和源码版本一致。修改插件后先停止宿主、复制对应产物再重启；框架未承诺任意已加载程序集都能通过文件覆盖立即热替换。

若宿主使用本地 framework 引用，还需匹配 Debug/Release 与目标框架。仅重建一个项目而遗漏它的依赖，可能导致符号不匹配或首次调用缺少方法。

## 配置与日志

记录应用名、内容根目录、环境和插件路径，再检查[选项文件匹配](/references/option-files.md)。诊断配置时只输出必要键和非秘密信息，避免打印完整连接字符串。

日志应保留异常类型和调用链。异步查询、流式响应或消息处理的错误可能在后续枚举/回调中出现，错误处理范围需要覆盖真实执行阶段。

## 建立可复现步骤

保存脱敏输入、运行版本、配置差异和预期/实际结果。先检查进程与插件装配，再执行论坛只读查询，再加入外部依赖和并发。涉及写入时使用独立测试数据，并明确清理对象。

进一步阅读：[宿主部署](/hosting/deployment.md)、[服务定位](/framework/core/services/locating.md)、[常见问题](/faq.md)。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.zongsoft.com/get-started/run-and-debug.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.